claude-flow 3.7.0-alpha.24 → 3.7.0-alpha.25

package/.claude/agents/dual-mode/codex-coordinator.md

@@ -5,7 +5,12 @@ description: Coordinates multiple headless Codex workers for parallel execution
 
 # Codex Parallel Coordinator
 
-You coordinate multiple headless Codex workers for parallel task execution. You run interactively and spawn background workers using `claude -p`.
+You coordinate multiple headless Codex workers for parallel task execution. You run interactively and spawn background workers using `codex exec`.
+
+> Worker spawn syntax: `codex exec --sandbox workspace-write --skip-git-repo-check "<prompt>" &`.
+> `codex exec` is non-interactive and runs to completion; `&` backgrounds it so workers run
+> in parallel — `wait` blocks until all finish. (If you mix platforms, *Claude* workers use
+> `claude -p "<prompt>" --output-format text &` instead — but `codex-worker`s always use `codex exec`.)
 
 ## Architecture
 
@@ -37,7 +42,7 @@ You coordinate multiple headless Codex workers for parallel task execution. You
 ## Core Responsibilities
 
 1. **Task Decomposition**: Break complex tasks into parallelizable units
-2. **Worker Spawning**: Launch headless Codex instances via `claude -p`
+2. **Worker Spawning**: Launch headless Codex instances via `codex exec`
 3. **Coordination**: Track progress through shared memory
 4. **Result Aggregation**: Collect and combine worker outputs
 
@@ -45,16 +50,16 @@ You coordinate multiple headless Codex workers for parallel task execution. You
 
 ### Step 1: Initialize Swarm
 ```bash
-npx claude-flow@v3alpha swarm init --topology hierarchical --max-agents 6
+npx ruflo@latest swarm init --topology hierarchical --max-agents 6
 ```
 
 ### Step 2: Spawn Parallel Workers
 ```bash
 # Spawn all workers in parallel
-claude -p "Implement core auth logic" --session-id auth-core &
-claude -p "Implement auth middleware" --session-id auth-middleware &
-claude -p "Write auth tests" --session-id auth-tests &
-claude -p "Document auth API" --session-id auth-docs &
+codex exec --sandbox workspace-write --skip-git-repo-check "Implement core auth logic. Store result in 'results' namespace as result-auth-core." &
+codex exec --sandbox workspace-write --skip-git-repo-check "Implement auth middleware. Store result as result-auth-middleware." &
+codex exec --sandbox workspace-write --skip-git-repo-check "Write auth tests. Store result as result-auth-tests." &
+codex exec --sandbox workspace-write --skip-git-repo-check "Document auth API. Store result as result-auth-docs." &
 
 # Wait for all to complete
 wait
@@ -62,7 +67,7 @@ wait
 
 ### Step 3: Collect Results
 ```bash
-npx claude-flow@v3alpha memory list --namespace results
+npx ruflo@latest memory list --namespace results
 ```
 
 ## Coordination Patterns
@@ -107,21 +112,21 @@ const workers = [
 
 // Spawn all workers
 workers.forEach(w => {
-  console.log(`claude -p "${w.task}" --session-id ${w.id} &`);
+  console.log(`codex exec --sandbox workspace-write --skip-git-repo-check "${w.task}. Store result as result-${w.id}." &`);
 });
 ```
 
 ### Worker Spawn Template
 ```bash
-claude -p "
-You are {{worker_name}}.
+codex exec --sandbox workspace-write --skip-git-repo-check "
+You are {{worker_name}} ({{worker_id}}).
 
 TASK: {{worker_task}}
 
 1. Search memory: memory_search(query='{{task_keywords}}')
 2. Execute your task
-3. Store results: memory_store(key='result-{{session_id}}', namespace='results', upsert=true)
-" --session-id {{session_id}} &
+3. Store results: memory_store(key='result-{{worker_id}}', namespace='results', upsert=true)
+" &
 ```
 
 ## MCP Tool Integration
@@ -129,7 +134,7 @@ TASK: {{worker_task}}
 ### Initialize Coordination
 ```javascript
 // Initialize swarm tracking
-mcp__ruv-swarm__swarm_init {
+mcp__ruflo__swarm_init {
   topology: "hierarchical",
   maxAgents: 8,
   strategy: "specialized"
@@ -139,7 +144,7 @@ mcp__ruv-swarm__swarm_init {
 ### Track Worker Status
 ```javascript
 // Store coordination state
-mcp__claude-flow__memory_store {
+mcp__ruflo__memory_store {
   key: "coordination/parallel-task",
   value: JSON.stringify({
     workers: ["worker-1", "worker-2", "worker-3"],
@@ -153,7 +158,7 @@ mcp__claude-flow__memory_store {
 ### Aggregate Results
 ```javascript
 // Collect all worker results
-mcp__claude-flow__memory_list {
+mcp__ruflo__memory_list {
   namespace: "results"
 }
 ```
@@ -165,37 +170,37 @@ mcp__claude-flow__memory_list {
 FEATURE="user-auth"
 
 # Initialize
-npx claude-flow@v3alpha swarm init --topology hierarchical --max-agents 4
+npx ruflo@latest swarm init --topology hierarchical --max-agents 4
 
 # Spawn workers in parallel
-claude -p "Architect: Design $FEATURE" --session-id ${FEATURE}-arch &
-claude -p "Coder: Implement $FEATURE" --session-id ${FEATURE}-code &
-claude -p "Tester: Test $FEATURE" --session-id ${FEATURE}-test &
-claude -p "Docs: Document $FEATURE" --session-id ${FEATURE}-docs &
+codex exec --sandbox workspace-write --skip-git-repo-check "Architect: Design $FEATURE. Store result as result-${FEATURE}-arch." &
+codex exec --sandbox workspace-write --skip-git-repo-check "Coder: Implement $FEATURE. Store result as result-${FEATURE}-code." &
+codex exec --sandbox workspace-write --skip-git-repo-check "Tester: Test $FEATURE. Store result as result-${FEATURE}-test." &
+codex exec --sandbox workspace-write --skip-git-repo-check "Docs: Document $FEATURE. Store result as result-${FEATURE}-docs." &
 
 # Wait for all
 wait
 
 # Collect results
-npx claude-flow@v3alpha memory list --namespace results
+npx ruflo@latest memory list --namespace results
 ```
 
 ## Best Practices
 
 1. **Size Workers Appropriately**: Each worker should complete in < 5 minutes
-2. **Use Meaningful IDs**: Session IDs should identify the worker's purpose
+2. **Use Meaningful IDs**: result keys should identify the worker's purpose
 3. **Share Context**: Store shared context in memory before spawning
-4. **Budget Limits**: Use `--max-budget-usd` to control costs
+4. **Pick a Sandbox**: `workspace-write` for code changes, `read-only` for audits/reviews
 5. **Error Handling**: Check for partial failures when collecting results
 
 ## Worker Types Reference
 
 | Type | Purpose | Spawn Command |
 |------|---------|---------------|
-| `coder` | Implement code | `claude -p "Implement [feature]"` |
-| `tester` | Write tests | `claude -p "Write tests for [module]"` |
-| `reviewer` | Review code | `claude -p "Review [files]"` |
-| `docs` | Documentation | `claude -p "Document [component]"` |
-| `architect` | Design | `claude -p "Design [system]"` |
+| `coder` | Implement code | `codex exec --sandbox workspace-write --skip-git-repo-check "Implement [feature]"` |
+| `tester` | Write tests | `codex exec --sandbox workspace-write --skip-git-repo-check "Write tests for [module]"` |
+| `reviewer` | Review code | `codex exec --sandbox read-only --skip-git-repo-check "Review [files]"` |
+| `docs` | Documentation | `codex exec --sandbox workspace-write --skip-git-repo-check "Document [component]"` |
+| `architect` | Design | `codex exec --sandbox read-only --skip-git-repo-check "Design [system]"` |
 
 Remember: You coordinate, workers execute. Use memory for all communication between processes.

package/.claude/agents/dual-mode/codex-worker.md

@@ -5,7 +5,13 @@ description: Headless Codex background worker for parallel task execution with s
 
 # Codex Headless Worker
 
-You are a headless Codex worker executing in background mode. You run independently via `claude -p` and coordinate with other workers through shared memory.
+You are a headless Codex worker executing in background mode. You run independently via `codex exec` and coordinate with other workers through shared memory.
+
+> Spawn syntax: `codex exec --sandbox workspace-write --skip-git-repo-check "<prompt>"`.
+> `codex exec` is non-interactive — it runs to completion and prints the agent's final
+> message to stdout. Append `&` to run several workers in parallel. (When the dual-mode
+> orchestrator mixes platforms, *Claude* workers use `claude -p "<prompt>" --output-format text`
+> instead — but a `codex-worker` is always launched with `codex exec`.)
 
 ## Execution Model
 
@@ -23,7 +29,8 @@ You are a headless Codex worker executing in background mode. You run independen
 │   ├─ worker-2 ──┤── Run in parallel            │
 │   └─ worker-3 ──┘                              │
 │                                                 │
-│   Each: claude -p "task" --session-id X &      │
+│   Each: codex exec --sandbox workspace-write   │
+│         --skip-git-repo-check "task" &          │
 └─────────────────────────────────────────────────┘
 ```
 
@@ -39,7 +46,7 @@ You are a headless Codex worker executing in background mode. You run independen
 ### Before Starting Task
 ```javascript
 // 1. Search for relevant patterns
-mcp__claude-flow__memory_search {
+mcp__ruflo__memory_search {
   query: "keywords from task",
   namespace: "patterns",
   limit: 5
@@ -52,7 +59,7 @@ mcp__claude-flow__memory_search {
 ### After Completing Task
 ```javascript
 // 3. Store what worked for future workers
-mcp__claude-flow__memory_store {
+mcp__ruflo__memory_store {
   key: "pattern-[task-type]",
   value: JSON.stringify({
     approach: "what worked",
@@ -63,8 +70,8 @@ mcp__claude-flow__memory_store {
 }
 
 // 4. Store result for coordinator
-mcp__claude-flow__memory_store {
-  key: "result-[session-id]",
+mcp__ruflo__memory_store {
+  key: "result-[worker-id]",
   value: JSON.stringify({
     status: "complete",
     summary: "what was done"
@@ -78,66 +85,66 @@ mcp__claude-flow__memory_store {
 
 ### Basic Worker
 ```bash
-claude -p "
-You are codex-worker.
+codex exec --sandbox workspace-write --skip-git-repo-check "
+You are codex-worker (worker-1).
 TASK: [task description]
 
 1. Search memory for patterns
 2. Execute the task
-3. Store results
-" --session-id worker-1 &
+3. Store results in the 'results' namespace
+" &
 ```
 
-### With Budget Limit
+### Pin a Model
 ```bash
-claude -p "Implement user auth" --max-budget-usd 0.50 --session-id auth-worker &
+codex exec --sandbox workspace-write --skip-git-repo-check -m gpt-5.3-codex "Implement user auth" &
 ```
 
-### With Specific Tools
+### Read-only Worker (no file writes)
 ```bash
-claude -p "Write tests for api.ts" --allowedTools "Read,Write,Bash" --session-id test-worker &
+codex exec --sandbox read-only --skip-git-repo-check "Audit src/api.ts for security issues" &
 ```
 
 ## Worker Types
 
 ### Coder Worker
 ```bash
-claude -p "
+codex exec --sandbox workspace-write --skip-git-repo-check "
 You are a coder worker.
 Implement: [feature]
 Path: src/[module]/
 Store results when complete.
-" --session-id coder-1 &
+" &
 ```
 
 ### Tester Worker
 ```bash
-claude -p "
+codex exec --sandbox workspace-write --skip-git-repo-check "
 You are a tester worker.
 Write tests for: [module]
 Path: tests/
 Run tests and store coverage results.
-" --session-id tester-1 &
+" &
 ```
 
 ### Documenter Worker
 ```bash
-claude -p "
+codex exec --sandbox workspace-write --skip-git-repo-check "
 You are a documentation writer.
 Document: [component]
 Output: docs/
 Store completion status.
-" --session-id docs-1 &
+" &
 ```
 
 ### Reviewer Worker
 ```bash
-claude -p "
+codex exec --sandbox read-only --skip-git-repo-check "
 You are a code reviewer.
 Review: [files]
 Check for: security, performance, best practices
 Store findings in memory.
-" --session-id reviewer-1 &
+" &
 ```
 
 ## MCP Tool Integration
@@ -145,13 +152,13 @@ Store findings in memory.
 ### Available Tools
 ```javascript
 // Search for patterns before starting
-mcp__claude-flow__memory_search {
+mcp__ruflo__memory_search {
   query: "[task keywords]",
   namespace: "patterns"
 }
 
 // Store results and patterns
-mcp__claude-flow__memory_store {
+mcp__ruflo__memory_store {
   key: "[result-key]",
   value: "[json-value]",
   namespace: "results",
@@ -159,25 +166,25 @@ mcp__claude-flow__memory_store {
 }
 
 // Check swarm status (optional)
-mcp__ruv-swarm__swarm_status {
+mcp__ruflo__swarm_status {
   verbose: true
 }
 ```
 
 ## Important Notes
 
-1. **Always Background**: Run with `&` for parallel execution
-2. **Use Session IDs**: Track workers with `--session-id`
-3. **Store Results**: Coordinator needs to collect your output
-4. **Budget Limits**: Use `--max-budget-usd` for cost control
-5. **Upsert Pattern**: Always use `upsert: true` to avoid duplicate key errors
+1. **Always Background**: append `&` so workers run in parallel
+2. **Pick a Sandbox**: `workspace-write` for code changes, `read-only` for audits/reviews
+3. **Store Results**: the coordinator collects your output from the `results` namespace
+4. **Git Check**: `--skip-git-repo-check` lets Codex run outside a git repo
+5. **Upsert Pattern**: always use `upsert: true` to avoid duplicate key errors
 
 ## Best Practices
 
 - Keep tasks focused and small (< 5 minutes each)
 - Search memory before starting to leverage past patterns
 - Store patterns that worked for future workers
-- Use meaningful session IDs for tracking
+- Use a clear worker id in your result keys for tracking
 - Store completion status even on partial success
 
-Remember: You run headlessly in background. The coordinator will collect your results via shared memory.
+Remember: You run headlessly in background. The coordinator collects your results via shared memory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.7.0-alpha.24",
+  "version": "3.7.0-alpha.25",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/dist/src/commands/start.js

@@ -278,7 +278,7 @@ const stopCommand = {
             spinner.setText('Stopping swarm...');
             spinner.start();
             try {
-                await callMCPTool('swarm_stop', {
+                await callMCPTool('swarm_shutdown', {
                     graceful: !force,
                     timeout,
                     saveState: true

package/v3/@claude-flow/cli/dist/src/commands/swarm.js

@@ -654,7 +654,7 @@ const stopCommand = {
         }
         // Attempt MCP cleanup
         try {
-            await callMCPTool('swarm_stop', { swarmId, force });
+            await callMCPTool('swarm_shutdown', { swarmId, force });
             output.writeln(output.dim('  MCP swarm stopped'));
         }
         catch {

package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.js

@@ -13,6 +13,11 @@ import { executeAgentTask } from './agent-execute-core.js';
 const STORAGE_DIR = '.claude-flow';
 const AGENT_DIR = 'agents';
 const AGENT_FILE = 'store.json';
+// #1916: hive-mind_spawn writes its workers to `.claude-flow/agents.json`
+// (a *different* file from the canonical `.claude-flow/agents/store.json`
+// used here). agent_status / agent_list / agent_logs merge that store so a
+// hive-spawned worker is resolvable instead of returning `not_found`.
+const HIVE_AGENT_FILE = 'agents.json';
 function getAgentDir() {
     return join(getProjectCwd(), STORAGE_DIR, AGENT_DIR);
 }
@@ -42,6 +47,33 @@ function saveAgentStore(store) {
     ensureAgentDir();
     writeFileSync(getAgentPath(), JSON.stringify(store, null, 2), 'utf-8');
 }
+// #1916: read hive-mind-spawned workers from `.claude-flow/agents.json`.
+function getHiveAgentPath() {
+    return join(getProjectCwd(), STORAGE_DIR, HIVE_AGENT_FILE);
+}
+function loadHiveAgents() {
+    try {
+        const path = getHiveAgentPath();
+        if (existsSync(path)) {
+            const data = JSON.parse(readFileSync(path, 'utf-8'));
+            if (data && typeof data.agents === 'object' && data.agents) {
+                return data.agents;
+            }
+        }
+    }
+    catch {
+        // Ignore — hive store is optional/best-effort.
+    }
+    return {};
+}
+/**
+ * #1916: merged view of every tracked agent — the canonical agent store
+ * plus hive-mind-spawned workers. On an id collision the canonical record
+ * wins (it carries model-routing + lastResult that the hive store omits).
+ */
+function loadAllAgents() {
+    return { ...loadHiveAgents(), ...loadAgentStore().agents };
+}
 // Default model mappings for agent types (can be overridden)
 const AGENT_TYPE_MODEL_DEFAULTS = {
     // Complex agents → opus
@@ -309,9 +341,8 @@ export const agentTools = [
             const v = validateIdentifier(input.agentId, 'agentId');
             if (!v.valid)
                 return { agentId: input.agentId, status: 'not_found', error: `Input validation failed: ${v.error}` };
-            const store = loadAgentStore();
             const agentId = input.agentId;
-            const agent = store.agents[agentId];
+            const agent = loadAllAgents()[agentId]; // #1916: includes hive-mind-spawned workers
             if (agent) {
                 return {
                     agentId: agent.agentId,
@@ -354,8 +385,7 @@ export const agentTools = [
                 if (!v.valid)
                     return { agents: [], total: 0, error: `Input validation failed: ${v.error}` };
             }
-            const store = loadAgentStore();
-            let agents = Object.values(store.agents);
+            let agents = Object.values(loadAllAgents()); // #1916: includes hive-mind-spawned workers
             // Filter by status
             if (input.status) {
                 agents = agents.filter(a => a.status === input.status);
@@ -635,5 +665,52 @@ export const agentTools = [
             };
         },
     },
+    {
+        // #1916 — the `ruflo agent logs <id>` CLI subcommand and the guidance
+        // surface both reference an `agent_logs` MCP tool that was never
+        // registered, so it errored with `MCP tool not found: agent_logs`.
+        // This is the registered handler. Note: agents don't yet keep a
+        // structured per-agent activity log (that lands with hive worker
+        // execution wiring — see #1916), so for now we surface the agent's
+        // last task result as a single synthetic entry, or an explicit empty
+        // response. The shape matches what the CLI `logs` subcommand expects:
+        // `{ agentId, entries: [{timestamp,level,message,context?}], total }`.
+        name: 'agent_logs',
+        description: 'Return recorded activity-log entries for a tracked agent (idle/running history, last task result). Use when native Task tool is wrong because you need the agent\'s log across turns (what it did, last error/result, swarm context) rather than a one-shot Task transcript. For a Task you just ran, native Task output is fine. Pair with agent_list to find the agentId. (Hive-mind-spawned workers are resolved here too.) Today this returns the last task result as a synthetic entry — full per-agent activity logs land with hive worker execution wiring (ruvnet/ruflo#1916).',
+        category: 'agent',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'ID of agent' },
+                tail: { type: 'number', description: 'Max recent entries to return (default 50)' },
+                level: { type: 'string', enum: ['debug', 'info', 'warn', 'error'], description: 'Minimum log level (currently advisory — entries are synthetic)' },
+                since: { type: 'string', description: 'Show logs since, e.g. "1h" / "30m" (currently advisory)' },
+            },
+            required: ['agentId'],
+        },
+        handler: async (input) => {
+            const v = validateIdentifier(input.agentId, 'agentId');
+            if (!v.valid)
+                return { agentId: input.agentId, entries: [], total: 0, error: `Input validation failed: ${v.error}` };
+            const agentId = input.agentId;
+            const agent = loadAllAgents()[agentId]; // #1916: includes hive-mind-spawned workers
+            if (!agent) {
+                return { agentId, entries: [], total: 0, error: 'Agent not found' };
+            }
+            const entries = [];
+            entries.push({ timestamp: agent.createdAt, level: 'info', message: `agent created (type=${agent.agentType}, status=${agent.status})` });
+            if (agent.lastResult) {
+                entries.push({ timestamp: agent.createdAt, level: 'info', message: 'last task result', context: agent.lastResult });
+            }
+            const tail = typeof input.tail === 'number' && input.tail > 0 ? Math.floor(input.tail) : 50;
+            const sliced = entries.slice(-tail);
+            return {
+                agentId: agent.agentId,
+                entries: sliced,
+                total: entries.length,
+                note: 'per-agent activity logging is not yet wired; entries are synthetic (ruvnet/ruflo#1916)',
+            };
+        },
+    },
 ];
 //# sourceMappingURL=agent-tools.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/hive-mind-tools.js

@@ -905,5 +905,49 @@ export const hiveMindTools = [
             return { action, error: 'Unknown action' };
         },
     },
+    {
+        // #1916: `ruflo hive-mind optimize-memory` referenced an unregistered
+        // `hive-mind_optimize-memory` tool. Best-effort today: prunes obviously-
+        // empty shared-memory keys and reports the before/after counts; pattern
+        // quality consolidation is a follow-up (it belongs in the intelligence
+        // pipeline / agentdb curator, not here).
+        name: 'hive-mind_optimize-memory',
+        description: 'Compact the hive-mind shared-memory store (drops null/empty keys) and report before/after pattern counts. Use when native conversation memory is wrong because you need the queen-led collective\'s persisted shared state cleaned up between phases. For one-shot scratch state, no tool needed. (Pattern-quality consolidation is delegated to the intelligence pipeline — this only does the cheap structural pass for now.)',
+        category: 'hive-mind',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                qualityThreshold: { type: 'number', description: 'Quality threshold for pattern retention (advisory — not enforced yet)' },
+            },
+        },
+        handler: async () => {
+            const t0 = Date.now();
+            const state = loadHiveState();
+            if (!state.initialized)
+                return { optimized: false, error: 'Hive-mind not initialized', before: { patterns: 0, memory: '0' }, after: { patterns: 0, memory: '0' }, removed: 0, consolidated: 0, timeMs: 0 };
+            const beforeKeys = Object.keys(state.sharedMemory);
+            const before = beforeKeys.length;
+            for (const k of beforeKeys) {
+                const v = state.sharedMemory[k];
+                if (v === null || v === undefined || (typeof v === 'object' && v !== null && Object.keys(v).length === 0)) {
+                    delete state.sharedMemory[k];
+                }
+            }
+            const after = Object.keys(state.sharedMemory).length;
+            const removed = before - after;
+            if (removed > 0)
+                saveHiveState(state);
+            const sizeStr = (n) => `${Buffer.byteLength(JSON.stringify(state.sharedMemory))}B (~${n} keys)`;
+            return {
+                optimized: removed > 0,
+                before: { patterns: before, memory: `~${before} keys` },
+                after: { patterns: after, memory: sizeStr(after) },
+                removed,
+                consolidated: 0,
+                timeMs: Date.now() - t0,
+                note: 'structural compaction only; pattern-quality consolidation is delegated to the intelligence pipeline (#1916 follow-up)',
+            };
+        },
+    },
 ];
 //# sourceMappingURL=hive-mind-tools.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.d.ts

@@ -39,6 +39,8 @@ export declare const hooksModelRoute: MCPTool;
 export declare const hooksModelOutcome: MCPTool;
 export declare const hooksModelStats: MCPTool;
 export declare const hooksWorkerCancel: MCPTool;
+export declare const hooksTeammateIdle: MCPTool;
+export declare const hooksTaskCompleted: MCPTool;
 export declare const hooksTools: MCPTool[];
 export default hooksTools;
 //# sourceMappingURL=hooks-tools.d.ts.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.js

@@ -3799,8 +3799,69 @@ export const hooksWorkerCancel = {
         };
     },
 };
+// #1916: the `ruflo hooks teammate-idle` / `ruflo hooks task-completed` CLI
+// subcommands (Agent Teams hooks) referenced unregistered tools. Minimal
+// acknowledgement handlers with the shapes the CLI expects — auto-assignment
+// and pattern-learning are delegated to the task-queue consumer / intelligence
+// pipeline (a tracked #1916 follow-up).
+export const hooksTeammateIdle = {
+    name: 'hooks_teammate-idle',
+    description: 'Agent Teams hook — fired when a teammate agent finishes its turn; reports whether a pending task can be auto-assigned. Use when native Task is wrong because you have a persistent multi-agent team with a shared task list and want idle workers picked up automatically rather than re-spawning subagents. For a one-shot Task, native Task is fine. (Auto-assignment is delegated to the task-queue consumer — this acknowledges the event today.)',
+    category: 'hooks',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            teammateId: { type: 'string', description: 'ID of the idle teammate' },
+            teamName: { type: 'string', description: 'Team name' },
+            autoAssign: { type: 'boolean', description: 'Auto-assign a pending task if available' },
+            checkTaskList: { type: 'boolean', description: 'Consult the shared task list' },
+            timestamp: { type: 'number', description: 'Event timestamp (ms)' },
+        },
+    },
+    handler: async (input) => {
+        const teammateId = String(input.teammateId ?? '');
+        return {
+            success: true,
+            teammateId,
+            action: 'waiting',
+            pendingTasks: 0,
+            message: 'teammate-idle acknowledged; auto-assignment requires the task-queue consumer (#1916 follow-up)',
+        };
+    },
+};
+export const hooksTaskCompleted = {
+    name: 'hooks_task-completed',
+    description: 'Agent Teams hook — fired when a task is marked complete; records completion and (eventually) trains patterns + notifies the team lead. Use when native TodoWrite is wrong because the work was a persisted, agent-assigned task whose outcome should feed cross-session learning and team coordination. For an in-session checklist tick, native TodoWrite is fine. (Pattern-learning is delegated to the intelligence pipeline — this records the completion today.)',
+    category: 'hooks',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            taskId: { type: 'string', description: 'ID of the completed task' },
+            teammateId: { type: 'string', description: 'Teammate that completed it' },
+            success: { type: 'boolean', description: 'Whether the task succeeded' },
+            quality: { type: 'number', description: 'Quality score 0-1' },
+            trainPatterns: { type: 'boolean', description: 'Feed the outcome to the learning pipeline' },
+            notifyLead: { type: 'boolean', description: 'Notify the team lead' },
+        },
+        required: ['taskId'],
+    },
+    handler: async (input) => {
+        const taskId = String(input.taskId ?? '');
+        const quality = typeof input.quality === 'number' ? input.quality : (input.success === false ? 0 : 1);
+        return {
+            success: true,
+            taskId,
+            patternsLearned: 0,
+            leadNotified: input.notifyLead === true,
+            metrics: { duration: 0, quality, learningUpdates: 0 },
+            note: 'completion recorded; pattern-learning is delegated to the intelligence pipeline (#1916 follow-up)',
+        };
+    },
+};
 // Export all hooks tools
 export const hooksTools = [
+    hooksTeammateIdle,
+    hooksTaskCompleted,
     hooksPreEdit,
     hooksPostEdit,
     hooksPreCommand,

package/v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.js

@@ -920,5 +920,227 @@ export const memoryTools = [
             };
         },
     },
+    {
+        // #1916: `ruflo status memory` (the detailed view) referenced an
+        // unregistered `memory_detailed-stats` tool. memory_stats returns a
+        // different shape; this returns what the CLI renders.
+        name: 'memory_detailed-stats',
+        description: 'Detailed memory-store report — backend, entry count, total bytes, per-namespace counts, and (placeholder) perf metrics. Use when native Read/Glob is wrong because the data lives in .swarm/memory.db, not files, and you want an aggregate health view. For a quick count use memory_stats; for "what is in memory" use memory_list.',
+        category: 'memory',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            await ensureInitialized();
+            const { listEntries } = await getMemoryFunctions();
+            const all = await listEntries({ limit: 100000 });
+            const nsCounts = {};
+            let bytes = 0;
+            for (const e of all.entries) {
+                nsCounts[e.namespace] = (nsCounts[e.namespace] || 0) + 1;
+                bytes += e.size || 0;
+            }
+            return {
+                backend: 'sql.js + HNSW',
+                entries: all.total ?? all.entries.length,
+                size: bytes,
+                namespaces: Object.entries(nsCounts).map(([name, entries]) => ({ name, entries })),
+                performance: { avgSearchTime: 0, avgWriteTime: 0, cacheHitRate: 0, hnswEnabled: true },
+                note: 'perf metrics are placeholders; HNSW is always enabled in the sql.js backend',
+            };
+        },
+    },
+    {
+        // #1916: `ruflo memory cleanup` referenced an unregistered `memory_cleanup`
+        // tool. Removes entries whose TTL has expired. Defaults to a dry run —
+        // pass dryRun:false to actually delete.
+        name: 'memory_cleanup',
+        description: 'Prune memory entries whose TTL has expired (dry run by default; pass dryRun:false to delete). Use when native rm is wrong because the entries are rows in .swarm/memory.db, not files. For removing a specific known key use memory_delete. Stale/low-quality pruning is delegated to the agentdb consolidation curator (#1916 follow-up).',
+        category: 'memory',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                dryRun: { type: 'boolean', description: 'Only report candidates, do not delete (default true)' },
+                namespace: { type: 'string', description: 'Limit cleanup to one namespace' },
+            },
+        },
+        handler: async (input) => {
+            await ensureInitialized();
+            const { listEntries, deleteEntry } = await getMemoryFunctions();
+            const dryRun = input.dryRun !== false; // default true
+            const namespace = input.namespace ? String(input.namespace) : undefined;
+            if (namespace) {
+                const v = validateIdentifier(namespace, 'namespace');
+                if (!v.valid)
+                    throw new Error(v.error);
+            }
+            const all = await listEntries({ limit: 100000, namespace });
+            const now = Date.now();
+            const expired = all.entries.filter(e => {
+                const exp = e.expiresAt;
+                if (!exp)
+                    return false;
+                const t = typeof exp === 'number' ? exp : Date.parse(String(exp));
+                return Number.isFinite(t) && t < now;
+            });
+            let freedBytes = 0;
+            let deleted = 0;
+            if (!dryRun) {
+                for (const e of expired) {
+                    try {
+                        await deleteEntry({ key: e.key, namespace: e.namespace });
+                        freedBytes += e.size || 0;
+                        deleted++;
+                    }
+                    catch { /* ignore individual delete errors */ }
+                }
+            }
+            else {
+                freedBytes = expired.reduce((s, e) => s + (e.size || 0), 0);
+            }
+            return {
+                dryRun,
+                candidates: { expired: expired.length, stale: 0, lowQuality: 0, total: expired.length },
+                deleted: { entries: dryRun ? 0 : deleted, vectors: 0, patterns: 0 },
+                freed: { bytes: freedBytes },
+                note: dryRun ? 'dry run — re-run with dryRun:false to delete' : undefined,
+            };
+        },
+    },
+    {
+        // #1916: `ruflo memory compress` referenced an unregistered tool. The
+        // sql.js backend has no on-disk compression; this reports current sizes.
+        name: 'memory_compress',
+        description: 'Report memory-store size breakdown (the sql.js backend has no on-disk compression — entries are already stored compactly; quantized embeddings via RaBitQ are configured elsewhere). Use when native du is wrong because the data is in .swarm/memory.db. For pruning expired entries use memory_cleanup.',
+        category: 'memory',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            await ensureInitialized();
+            const { listEntries } = await getMemoryFunctions();
+            const all = await listEntries({ limit: 100000 });
+            const bytes = all.entries.reduce((s, e) => s + (e.size || 0), 0);
+            const human = `${bytes}B`;
+            const sizes = { totalSize: human, vectorsSize: 'n/a', textSize: human, patternsSize: 'n/a', indexSize: 'n/a' };
+            return {
+                before: sizes,
+                after: sizes,
+                compression: { ratio: 1, savedBytes: 0, method: 'none' },
+                note: 'sql.js backend has no on-disk compression; nothing to compress. (RaBitQ embedding quantization is a separate feature.)',
+            };
+        },
+    },
+    {
+        // #1916: `ruflo memory export -o <file>` referenced an unregistered tool.
+        // Dumps entry metadata (and values when the backend returns them) to JSON.
+        name: 'memory_export',
+        description: 'Export memory entries to a JSON file (keys, namespaces, timestamps, and values when available). Use when native Write is wrong because the data is rows in .swarm/memory.db, not a file you can copy. For ingesting an export elsewhere use memory_import. (CSV output and embedding-vector export are follow-ups.)',
+        category: 'memory',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                outputPath: { type: 'string', description: 'File path to write the JSON export to' },
+                format: { type: 'string', enum: ['json', 'csv'], description: 'Export format (csv falls back to json today)' },
+                namespace: { type: 'string', description: 'Limit export to one namespace' },
+                includeVectors: { type: 'boolean', description: 'Include embedding vectors (advisory — not exported yet)' },
+            },
+            required: ['outputPath'],
+        },
+        handler: async (input) => {
+            await ensureInitialized();
+            const { listEntries } = await getMemoryFunctions();
+            const outputPath = String(input.outputPath ?? '');
+            if (!outputPath)
+                return { error: 'outputPath is required' };
+            const namespace = input.namespace ? String(input.namespace) : undefined;
+            if (namespace) {
+                const v = validateIdentifier(namespace, 'namespace');
+                if (!v.valid)
+                    throw new Error(v.error);
+            }
+            const all = await listEntries({ limit: 100000, namespace });
+            const payload = {
+                schema: 'ruflo-memory-export/v1',
+                exportedAt: new Date().toISOString(),
+                namespace: namespace ?? null,
+                count: all.entries.length,
+                entries: all.entries.map(e => ({
+                    key: e.key, namespace: e.namespace, value: e.value ?? null,
+                    createdAt: e.createdAt, updatedAt: e.updatedAt, accessCount: e.accessCount, hasEmbedding: e.hasEmbedding, size: e.size,
+                })),
+            };
+            try {
+                writeFileSync(outputPath, JSON.stringify(payload, null, 2), 'utf-8');
+            }
+            catch (e) {
+                return { error: `Could not write ${outputPath}: ${e.message}` };
+            }
+            const vectorsWithEmb = all.entries.filter(e => e.hasEmbedding).length;
+            return {
+                outputPath,
+                format: input.format || 'json',
+                exported: { entries: all.entries.length, vectors: vectorsWithEmb, patterns: 0 },
+                fileSize: `${Buffer.byteLength(JSON.stringify(payload))}B`,
+                note: input.format === 'csv' ? 'CSV not implemented yet — wrote JSON' : undefined,
+            };
+        },
+    },
+    {
+        // #1916: `ruflo memory import <file>` referenced an unregistered tool.
+        // Reads a ruflo-memory-export JSON and re-stores each entry.
+        name: 'memory_import',
+        description: 'Import memory entries from a JSON export file (produced by memory_export) into .swarm/memory.db, re-embedding values. Use when native Read is wrong because the data must be re-stored as memory rows (with new embeddings), not just read. For importing Claude Code\'s own memory files use memory_import_claude. Pair with memory_export on the source.',
+        category: 'memory',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                inputPath: { type: 'string', description: 'Path to the JSON export file' },
+                merge: { type: 'boolean', description: 'Merge into existing entries (upsert) vs. fail on conflict (default true)' },
+                namespace: { type: 'string', description: 'Override the namespace for all imported entries' },
+            },
+            required: ['inputPath'],
+        },
+        handler: async (input) => {
+            await ensureInitialized();
+            const { storeEntry } = await getMemoryFunctions();
+            const t0 = Date.now();
+            const inputPath = String(input.inputPath ?? '');
+            if (!inputPath || !existsSync(inputPath))
+                return { error: `File not found: ${inputPath || '(empty)'}` };
+            let doc;
+            try {
+                doc = JSON.parse(readFileSync(inputPath, 'utf-8'));
+            }
+            catch (e) {
+                return { error: `Invalid export JSON: ${e.message}` };
+            }
+            const entries = Array.isArray(doc.entries) ? doc.entries : [];
+            const nsOverride = input.namespace ? String(input.namespace) : undefined;
+            if (nsOverride) {
+                const v = validateIdentifier(nsOverride, 'namespace');
+                if (!v.valid)
+                    throw new Error(v.error);
+            }
+            let imported = 0;
+            let skipped = 0;
+            for (const e of entries) {
+                if (!e || typeof e.key !== 'string') {
+                    skipped++;
+                    continue;
+                }
+                const value = typeof e.value === 'string' ? e.value : JSON.stringify(e.value ?? null);
+                try {
+                    await storeEntry({ key: e.key, value, namespace: nsOverride ?? e.namespace ?? 'default', upsert: input.merge !== false });
+                    imported++;
+                }
+                catch {
+                    skipped++;
+                }
+            }
+            return {
+                inputPath,
+                imported: { entries: imported, vectors: 0, patterns: 0 },
+                skipped,
+                duration: Date.now() - t0,
+            };
+        },
+    },
 ];
 //# sourceMappingURL=memory-tools.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/session-tools.js

@@ -3,7 +3,7 @@
  *
  * Tool definitions for session management with file persistence.
  */
-import { existsSync, readFileSync, readdirSync, unlinkSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, unlinkSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getProjectCwd } from './types.js';
 import { mkdirRestricted, readFileMaybeEncrypted, writeFileRestricted, } from '../fs-secure.js';
@@ -389,5 +389,129 @@ export const sessionTools = [
             };
         },
     },
+    {
+        // #1916: `ruflo session current` referenced an unregistered
+        // `session_current` tool. Returns the most-recently-saved session.
+        name: 'session_current',
+        description: 'Return the most-recently-saved session (id, name, stats) — the de-facto "current" one. Use when native conversation memory is wrong because you need to know which durable session is active before exporting/restoring it. For in-session continuation only, no tool needed. Pair with session_export / session_restore.',
+        category: 'session',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            const dir = getSessionDir();
+            if (!existsSync(dir))
+                return { sessionId: '', status: 'none', startedAt: '', error: 'No saved sessions' };
+            const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+            if (files.length === 0)
+                return { sessionId: '', status: 'none', startedAt: '', error: 'No saved sessions' };
+            let newest = files[0];
+            let newestMtime = 0;
+            for (const f of files) {
+                const mt = statSync(join(dir, f)).mtimeMs;
+                if (mt >= newestMtime) {
+                    newestMtime = mt;
+                    newest = f;
+                }
+            }
+            const sessionId = newest.replace(/\.json$/, '');
+            const session = loadSession(sessionId);
+            if (!session)
+                return { sessionId, status: 'unknown', startedAt: '', error: 'Session file unreadable' };
+            return {
+                sessionId: session.sessionId,
+                name: session.name,
+                status: 'active',
+                startedAt: session.savedAt,
+                stats: session.stats,
+            };
+        },
+    },
+    {
+        // #1916: `ruflo session export <id> -o <file>` referenced an unregistered
+        // `session_export` tool. Writes the session JSON to a file (if given) and
+        // returns the session payload.
+        name: 'session_export',
+        description: 'Export a saved session (agents, tasks, memory snapshot) to a JSON file and/or return the payload. Use when native Write is wrong because the data is the structured session record (not a freeform file) and you want it serialized consistently for transfer/backup. For writing arbitrary content, native Write is fine. Pair with session_import on the other end.',
+        category: 'session',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: { type: 'string', description: 'Session ID to export' },
+                outputPath: { type: 'string', description: 'File path to write the export to (optional)' },
+                includeMemory: { type: 'boolean', description: 'Include the memory snapshot (advisory — already in the saved record)' },
+            },
+            required: ['sessionId'],
+        },
+        handler: async (input) => {
+            const vId = validateIdentifier(input.sessionId, 'sessionId');
+            if (!vId.valid)
+                return { success: false, error: vId.error };
+            const sessionId = input.sessionId;
+            const session = loadSession(sessionId);
+            if (!session)
+                return { sessionId, error: 'Session not found' };
+            let path = null;
+            const outputPath = input.outputPath ? String(input.outputPath) : null;
+            if (outputPath) {
+                try {
+                    writeFileSync(outputPath, JSON.stringify(session, null, 2), 'utf-8');
+                    path = outputPath;
+                }
+                catch (e) {
+                    return { sessionId, error: `Could not write ${outputPath}: ${e.message}` };
+                }
+            }
+            return { sessionId, name: session.name, data: session, path, exportedAt: new Date().toISOString() };
+        },
+    },
+    {
+        // #1916: `ruflo session import <file>` referenced an unregistered
+        // `session_import` tool. Reads a session JSON and re-saves it locally.
+        name: 'session_import',
+        description: 'Import a session JSON file (produced by session_export) into the local session store and optionally activate it. Use when native Read is wrong because the file is a structured session record that must be re-registered (new id, stats recomputed) rather than just read. For reading the file, native Read is fine. Pair with session_export on the source.',
+        category: 'session',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                inputPath: { type: 'string', description: 'Path to the session JSON file to import' },
+                name: { type: 'string', description: 'Override the imported session name' },
+                activate: { type: 'boolean', description: 'Make the imported session the current one (advisory)' },
+            },
+            required: ['inputPath'],
+        },
+        handler: async (input) => {
+            const inputPath = String(input.inputPath ?? '');
+            if (!inputPath || !existsSync(inputPath))
+                return { error: `File not found: ${inputPath || '(empty)'}` };
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(inputPath, 'utf-8'));
+            }
+            catch (e) {
+                return { error: `Invalid session JSON: ${e.message}` };
+            }
+            const newId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const stats = parsed.stats || { tasks: 0, agents: 0, memoryEntries: 0, totalSize: 0 };
+            const session = {
+                sessionId: newId,
+                name: input.name ? String(input.name) : (parsed.name || 'imported-session'),
+                description: parsed.description,
+                savedAt: new Date().toISOString(),
+                stats,
+                data: parsed.data,
+            };
+            saveSession(session);
+            return {
+                sessionId: newId,
+                name: session.name,
+                importedAt: session.savedAt,
+                stats: {
+                    agentsImported: stats.agents,
+                    tasksImported: stats.tasks,
+                    memoryEntriesImported: stats.memoryEntries,
+                },
+                activated: input.activate === true,
+            };
+        },
+    },
 ];
 //# sourceMappingURL=session-tools.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/system-tools.js

@@ -622,5 +622,53 @@ export const systemTools = [
             };
         },
     },
+    {
+        // #1916: `ruflo start` referenced an unregistered `mcp_start` tool. MCP
+        // tools run *in-process* via the CLI's TOOL_REGISTRY — there is no
+        // separate server process to spawn from inside an MCP call. If this tool
+        // responds, MCP is already up. (`ruflo mcp start` runs a standalone
+        // stdio/HTTP server; that's a process command, not an MCP tool.)
+        name: 'mcp_start',
+        description: 'Report that the in-process MCP toolset is available (no-op "start" — if this tool responds, MCP is up). Use when native `claude mcp list` is wrong because you want Ruflo-side confirmation that the in-process registry loaded. For a standalone stdio/HTTP MCP server, run `ruflo mcp start` (a process command, not this tool). Pair with mcp_status for detail.',
+        category: 'system',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                port: { type: 'number', description: 'Port (advisory — in-process MCP has no port)' },
+                transport: { type: 'string', description: 'Transport (advisory)' },
+                tools: { type: 'array', items: { type: 'string' }, description: 'Tool namespaces (advisory — all are loaded)' },
+            },
+        },
+        handler: async (input) => {
+            const isStdio = !process.stdin.isTTY;
+            return {
+                serverId: `in-process-${process.pid}`,
+                port: typeof input.port === 'number' ? input.port : (parseInt(process.env.CLAUDE_FLOW_MCP_PORT || '0', 10) || null),
+                transport: input.transport || process.env.CLAUDE_FLOW_MCP_TRANSPORT || (isStdio ? 'stdio' : 'in-process'),
+                startedAt: new Date().toISOString(),
+                note: 'MCP tools run in-process via the CLI; no separate server process was started. Use `ruflo mcp start` for a standalone server.',
+            };
+        },
+    },
+    {
+        // #1916: `ruflo stop` referenced an unregistered `mcp_stop` tool. Same
+        // story as mcp_start — nothing to stop for the in-process registry.
+        name: 'mcp_stop',
+        description: 'No-op "stop" for the in-process MCP toolset (there is no separate server process to stop from inside an MCP call). Use when native process-kill is wrong because you mistakenly think Ruflo runs a daemon — it does not, the tools live in the CLI process. To stop a standalone server run `ruflo mcp stop` or terminate that process. Pair with mcp_status.',
+        category: 'system',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                graceful: { type: 'boolean', description: 'Advisory (no-op)' },
+                timeout: { type: 'number', description: 'Advisory (no-op)' },
+            },
+        },
+        handler: async () => {
+            return {
+                stopped: false,
+                note: 'no separate MCP server process; nothing to stop. The in-process toolset goes away when the CLI process exits. Use `ruflo mcp stop` for a standalone server.',
+            };
+        },
+    },
 ];
 //# sourceMappingURL=system-tools.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/task-tools.js

@@ -435,5 +435,53 @@ export const taskTools = [
             };
         },
     },
+    {
+        // #1916: the `ruflo task retry <id>` CLI subcommand referenced an
+        // unregistered `task_retry` tool. Re-queues a finished/cancelled task by
+        // cloning its spec into a fresh pending task (the original is left intact
+        // as history).
+        name: 'task_retry',
+        description: 'Re-queue a failed/cancelled/completed task by cloning its spec into a fresh pending task (the original record is kept as history). Use when native TodoWrite is wrong because you need the original task\'s persisted spec (type, priority, assignees, tags) and a stable taskId chain across runs rather than hand-retyping a checklist item. For ad-hoc re-runs, native TodoWrite is fine.',
+        category: 'task',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                taskId: { type: 'string', description: 'ID of the task to retry' },
+                resetState: { type: 'boolean', description: 'Reset progress/result on the new task (default true)' },
+            },
+            required: ['taskId'],
+        },
+        handler: async (input) => {
+            const v = validateIdentifier(input.taskId, 'taskId');
+            if (!v.valid)
+                return { success: false, error: v.error };
+            const store = loadTaskStore();
+            const taskId = input.taskId;
+            const original = store.tasks[taskId];
+            if (!original)
+                return { success: false, taskId, error: 'Task not found' };
+            const newTaskId = `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            store.tasks[newTaskId] = {
+                taskId: newTaskId,
+                type: original.type,
+                description: original.description,
+                priority: original.priority,
+                status: 'pending',
+                progress: 0,
+                assignedTo: [...original.assignedTo],
+                tags: [...original.tags, 'retry-of:' + taskId],
+                createdAt: new Date().toISOString(),
+                startedAt: null,
+                completedAt: null,
+            };
+            saveTaskStore(store);
+            return {
+                taskId,
+                newTaskId,
+                previousStatus: original.status,
+                status: 'pending',
+            };
+        },
+    },
 ];
 //# sourceMappingURL=task-tools.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/workflow-tools.js

@@ -772,5 +772,113 @@ export const workflowTools = [
             return { action, error: 'Unknown action' };
         },
     },
+    {
+        // #1916: `ruflo workflow stop <id>` referenced an unregistered
+        // `workflow_stop` tool. Equivalent to workflow_cancel but returns the
+        // shape the CLI expects (`{ workflowId, stopped, stoppedAt }`).
+        name: 'workflow_stop',
+        description: 'Stop a running/paused workflow and skip its remaining steps. Use when native TodoWrite + sequential Bash is wrong because the work has a real dependency graph that needs persistence, pause/resume, and step-output binding — and you need to halt it cleanly mid-run. For a single linear todo list, native TodoWrite is fine. (Same effect as workflow_cancel; this name is what the CLI `workflow stop` subcommand calls.)',
+        category: 'workflow',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workflowId: { type: 'string', description: 'Workflow ID' },
+                graceful: { type: 'boolean', description: 'Let the current step finish (advisory)' },
+            },
+            required: ['workflowId'],
+        },
+        handler: async (input) => {
+            const vId = validateIdentifier(input.workflowId, 'workflowId');
+            if (!vId.valid)
+                return { success: false, error: vId.error };
+            const store = loadWorkflowStore();
+            const workflowId = input.workflowId;
+            const workflow = store.workflows[workflowId];
+            if (!workflow)
+                return { workflowId, error: 'Workflow not found' };
+            if (workflow.status === 'completed' || workflow.status === 'failed') {
+                return { workflowId, error: 'Workflow already finished' };
+            }
+            workflow.status = 'failed';
+            workflow.error = 'Stopped by user';
+            workflow.completedAt = new Date().toISOString();
+            for (let i = workflow.currentStep; i < workflow.steps.length; i++) {
+                workflow.steps[i].status = 'skipped';
+            }
+            saveWorkflowStore(store);
+            return { workflowId, stopped: true, stoppedAt: workflow.completedAt };
+        },
+    },
+    {
+        // #1916: `ruflo workflow validate -f <file>` referenced an unregistered
+        // `workflow_validate` tool. Structural sanity check (JSON workflow files);
+        // a full schema validator is a follow-up.
+        name: 'workflow_validate',
+        description: 'Structurally validate a workflow definition file (JSON) — checks it has a steps/stages/tasks array and that each step names an agent. Use when native Read is wrong because you want a parsed, structured pass/fail with error/warning lists and step/agent counts rather than eyeballing the file. For just reading the file, native Read is fine. (Basic checks today — a full workflow-schema validator is a tracked follow-up.)',
+        category: 'workflow',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                file: { type: 'string', description: 'Path to the workflow definition file' },
+                strict: { type: 'boolean', description: 'Treat warnings as errors' },
+            },
+            required: ['file'],
+        },
+        handler: async (input) => {
+            const file = String(input.file ?? '');
+            const errors = [];
+            const warnings = [];
+            let stages = 0;
+            let agents = 0;
+            try {
+                if (!file || !existsSync(file)) {
+                    errors.push({ line: 0, message: `File not found: ${file || '(empty)'}`, severity: 'error' });
+                }
+                else {
+                    const raw = readFileSync(file, 'utf-8');
+                    let doc = null;
+                    if (/\.ya?ml$/i.test(file)) {
+                        warnings.push({ line: 0, message: 'YAML workflow files are not schema-validated yet — only JSON is fully checked (#1916 follow-up)' });
+                        try {
+                            doc = JSON.parse(raw);
+                        }
+                        catch { /* not JSON; leave doc null */ }
+                    }
+                    else {
+                        doc = JSON.parse(raw);
+                    }
+                    const d = (doc ?? {});
+                    const steps = (d.steps ?? d.stages ?? d.tasks);
+                    if (!Array.isArray(steps)) {
+                        errors.push({ line: 0, message: 'Workflow has no `steps` / `stages` / `tasks` array', severity: 'error' });
+                    }
+                    else {
+                        stages = steps.length;
+                        const agentSet = new Set();
+                        steps.forEach((s, i) => {
+                            const step = (s ?? {});
+                            const a = (step.agent ?? step.agentType ?? step.agent_type);
+                            if (a)
+                                agentSet.add(String(a));
+                            else
+                                warnings.push({ line: i + 1, message: `step ${i + 1} ("${step.name ?? step.id ?? i + 1}") names no agent` });
+                        });
+                        agents = agentSet.size;
+                    }
+                }
+            }
+            catch (e) {
+                errors.push({ line: 0, message: `Parse error: ${e.message}`, severity: 'error' });
+            }
+            const valid = errors.length === 0 && (!input.strict || warnings.length === 0);
+            return {
+                valid,
+                file,
+                errors,
+                warnings,
+                stats: { stages, agents, estimatedDuration: stages > 0 ? `~${stages * 30}s` : 'unknown' },
+            };
+        },
+    },
 ];
 //# sourceMappingURL=workflow-tools.js.map

package/v3/@claude-flow/cli/dist/src/ruvector/coverage-tools.js

@@ -12,7 +12,7 @@ import { coverageRoute, coverageSuggest, coverageGaps, } from './coverage-router
  * Uses ruvector's hooks_coverage_route when available.
  */
 export const hooksCoverageRoute = {
-    name: 'hooks/coverage-route',
+    name: 'hooks_coverage-route',
     description: 'Route task to agents based on test coverage gaps (ruvector integration)',
     category: 'coverage',
     tags: ['coverage', 'routing', 'testing', 'ruvector'],
@@ -57,7 +57,7 @@ export const hooksCoverageRoute = {
  * Uses ruvector's hooks_coverage_suggest when available.
  */
 export const hooksCoverageSuggest = {
-    name: 'hooks/coverage-suggest',
+    name: 'hooks_coverage-suggest',
     description: 'Suggest coverage improvements for a path (ruvector integration)',
     category: 'coverage',
     tags: ['coverage', 'suggestions', 'testing', 'ruvector'],
@@ -107,7 +107,7 @@ export const hooksCoverageSuggest = {
  * Lists all coverage gaps in the project with agent assignments.
  */
 export const hooksCoverageGaps = {
-    name: 'hooks/coverage-gaps',
+    name: 'hooks_coverage-gaps',
     description: 'List all coverage gaps with priority scoring and agent assignments',
     category: 'coverage',
     tags: ['coverage', 'gaps', 'testing', 'analysis'],

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.7.0-alpha.24",
+  "version": "3.7.0-alpha.25",
   "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",