claude-flow 3.6.28 → 3.6.30

package/.claude/agents/core/coder.md

@@ -7,6 +7,17 @@ description: Implementation specialist for writing clean, efficient code
 
 You are a senior software engineer specialized in writing clean, maintainable, and efficient code following best practices and design patterns.
 
+## Authoritative project documents — read before implementing
+
+Before writing code that affects architecture, scope, or behavior, read **both**:
+
+1. **`docs/SPEC.md`** (and any sibling files under `docs/`) — describes **what** the system should do. Functional requirements, scope, acceptance criteria.
+2. **`docs/adr/*.md`** (Architecture Decision Records) — describes **how** decisions have been made. Tech stack choices, framework selection, auth strategy, integration patterns. Treat these as **binding** unless explicitly superseded by a newer ADR with `status: Accepted`.
+
+If both exist and conflict, the ADR wins on architectural decisions; SPEC wins on requirements scope. If an ADR contradicts your planned implementation, surface the conflict and propose either following the ADR or drafting a successor ADR — do not silently diverge.
+
+When neither file exists (greenfield work), you can proceed without — but if a sibling Architect agent generated ADRs in this session, those ADRs are authoritative for your work even before they land in `docs/adr/`. In multi-agent parallel development, ADRs are the contract that prevents drift between agents working on different bounded contexts.
+
 ## Core Responsibilities
 
 1. **Code Implementation**: Write production-quality code that meets requirements

package/.claude/agents/templates/implementer-sparc-coder.md

@@ -8,6 +8,18 @@ description: Transform specifications into working code with TDD practices
 ## Purpose
 This agent specializes in the implementation phases of SPARC methodology, focusing on transforming specifications and designs into high-quality, tested code.
 
+## Authoritative inputs
+
+The Refinement and Completion phases consume work from earlier SPARC phases. Read **all** of the following before implementing:
+
+1. **`docs/SPEC.md`** — Specification phase output (what to build)
+2. **`docs/pseudocode/*.md`** if present — Pseudocode phase output (algorithm shape)
+3. **`docs/adr/*.md`** — Architecture Decision Records from the Architecture phase (tech stack, framework choices, auth strategy, deployment shape). **Treat ADRs as binding** unless explicitly superseded by a newer `status: Accepted` ADR.
+
+ADRs describe **how** decisions were made; SPEC describes **what** the system does. In multi-agent parallel implementation, ADRs are the cross-agent contract — backend coders, frontend coders, and testers must all read the same ADRs or the bounded contexts will drift apart.
+
+If your planned implementation contradicts an ADR, surface the conflict and propose either following the ADR or drafting a successor — do not silently diverge.
+
 ## Core Implementation Principles
 
 ### 1. Test-Driven Development (TDD)

package/README.md

@@ -156,8 +156,11 @@ This adds slash commands and agent definitions only. The Ruflo MCP server is NOT
 # One-line install
 curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash
 
-# Or via npx
-npx ruflo@latest init --wizard
+# Or via npx (interactive setup)
+npx ruflo@latest init wizard
+
+# Quick non-interactive init
+# npx ruflo@latest init
 
 # Or install globally
 npm install -g ruflo@latest
@@ -166,8 +169,8 @@ npm install -g ruflo@latest
 ### MCP Server
 
 ```bash
-# Add Ruflo as an MCP server in Claude Code
-claude mcp add ruflo -- npx -y @claude-flow/cli@latest
+# Add Ruflo as an MCP server in Claude Code (canonical form, matches USERGUIDE.md)
+claude mcp add ruflo -- npx ruflo@latest mcp start
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.6.28",
+  "version": "3.6.30",
   "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/README.md

@@ -156,8 +156,11 @@ This adds slash commands and agent definitions only. The Ruflo MCP server is NOT
 # One-line install
 curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash
 
-# Or via npx
-npx ruflo@latest init --wizard
+# Or via npx (interactive setup)
+npx ruflo@latest init wizard
+
+# Quick non-interactive init
+# npx ruflo@latest init
 
 # Or install globally
 npm install -g ruflo@latest
@@ -166,8 +169,8 @@ npm install -g ruflo@latest
 ### MCP Server
 
 ```bash
-# Add Ruflo as an MCP server in Claude Code
-claude mcp add ruflo -- npx -y @claude-flow/cli@latest
+# Add Ruflo as an MCP server in Claude Code (canonical form, matches USERGUIDE.md)
+claude mcp add ruflo -- npx ruflo@latest mcp start
 ```
 
 ---

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

@@ -10,6 +10,7 @@ import { select, confirm, input } from '../prompt.js';
 import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { spawn as childSpawn, execSync } from 'child_process';
 import { mkdir, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
 import { join } from 'path';
 // Hive topologies
 const TOPOLOGIES = [
@@ -200,6 +201,40 @@ async function spawnClaudeCodeInstance(swarmId, swarmName, objective, workers, f
         if (claudeAvailable && !dryRun) {
             // Build arguments - flags first, then prompt
             const claudeArgs = [];
+            // #1748 Issue 2 — pass --mcp-config so the spawned worker actually has
+            // mcp__ruflo__* tools registered. Before this, the coordination prompt
+            // referenced tools the worker didn't know about and exited silently.
+            // Resolution order:
+            //   1. explicit --mcp-config <path> flag passed by the caller
+            //   2. ./.mcp.json in cwd (project-local Ruflo MCP config)
+            //   3. ~/.claude.json or ~/.claude/mcp.json (user-global)
+            // If none found, we still spawn but warn — that's the pre-fix behavior
+            // and the user's debug log will surface the missing tools.
+            const explicitMcpConfig = flags['mcp-config'];
+            let mcpConfigPath = explicitMcpConfig;
+            if (!mcpConfigPath) {
+                const candidates = [
+                    join(process.cwd(), '.mcp.json'),
+                    join(process.env.HOME || process.env.USERPROFILE || '', '.claude.json'),
+                    join(process.env.HOME || process.env.USERPROFILE || '', '.claude', 'mcp.json'),
+                ];
+                for (const c of candidates) {
+                    try {
+                        if (c && existsSync(c)) {
+                            mcpConfigPath = c;
+                            break;
+                        }
+                    }
+                    catch { /* continue */ }
+                }
+            }
+            if (mcpConfigPath) {
+                claudeArgs.push('--mcp-config', mcpConfigPath);
+                output.printInfo(`Spawned worker MCP config: ${mcpConfigPath}`);
+            }
+            else {
+                output.printWarning('No .mcp.json or ~/.claude.json found — spawned worker will not have mcp__ruflo__* tools (#1748 Issue 2). Pass --mcp-config <path> or run "ruflo init" to generate one.');
+            }
             // Check for non-interactive mode
             const isNonInteractive = flags['non-interactive'] || flags.nonInteractive;
             if (isNonInteractive) {
@@ -492,6 +527,11 @@ const spawnCommand = {
             description: 'Run Claude Code in non-interactive mode',
             type: 'boolean',
             default: false
+        },
+        {
+            name: 'mcp-config',
+            description: 'Path to .mcp.json for the spawned worker (auto-detects ./.mcp.json or ~/.claude.json if omitted) — fixes #1748 Issue 2',
+            type: 'string'
         }
     ],
     examples: [

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

@@ -135,7 +135,7 @@ async function determineAgentModel(agentType, config, task) {
 export const agentTools = [
     {
         name: 'agent_spawn',
-        description: 'Spawn a new agent with intelligent model selection',
+        description: 'Spawn a Ruflo-tracked agent with cost attribution + memory persistence + swarm coordination. Use when native Task tool is wrong because you need (a) cost tracking per agent in the cost-tracking namespace, (b) cross-session learning via the patterns namespace, or (c) coordination with other agents in a swarm topology (hierarchical / mesh / consensus). For one-shot subtasks with no learning loop, native Task is fine. Pair with hooks_route to pick the right model first.',
         category: 'agent',
         inputSchema: {
             type: 'object',

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

@@ -759,7 +759,7 @@ export const hooksPostCommand = {
 };
 export const hooksRoute = {
     name: 'hooks_route',
-    description: 'Route task to optimal agent using semantic similarity (native HNSW or pure JS)',
+    description: 'Get a 3-tier routing recommendation for a task: Tier 1 (Agent Booster, 0ms / $0 — for var-to-const, add-types, etc.), Tier 2 (Haiku — simple), Tier 3 (Sonnet/Opus — complex). Use this BEFORE spawning an agent to avoid sending simple transforms to Sonnet. Native tools have no equivalent — Claude Code does not introspect its own model-selection cost. Returns the recommended model + a `[AGENT_BOOSTER_AVAILABLE]` literal when the WASM bypass applies.',
     inputSchema: {
         type: 'object',
         properties: {

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

@@ -153,7 +153,7 @@ async function ensureInitialized() {
 export const memoryTools = [
     {
         name: 'memory_store',
-        description: 'Store a value in memory with vector embedding for semantic search (sql.js + HNSW backend). Use upsert=true to update existing keys.',
+        description: 'Persistent key-value store with vector embedding — survives across sessions and is searchable by meaning, not just by file path. Use when native Write is wrong because the data is not a file (e.g. a learned pattern, a decision, a budget config) AND you need to recall it later by semantic query, not by path. Defaults to namespace="default"; pass --upsert=true to update an existing key.',
         category: 'memory',
         inputSchema: {
             type: 'object',
@@ -227,7 +227,7 @@ export const memoryTools = [
     },
     {
         name: 'memory_retrieve',
-        description: 'Retrieve a value from memory by key',
+        description: 'Read back a value previously stored via memory_store, by exact (namespace, key) — lossless, includes metadata. Use when native Read is wrong because the value is not a file (it lives in the .swarm/memory.db SQLite store) AND you know the exact key. For semantic lookup by meaning, use memory_search.',
         category: 'memory',
         inputSchema: {
             type: 'object',
@@ -287,7 +287,7 @@ export const memoryTools = [
     },
     {
         name: 'memory_search',
-        description: 'Semantic vector search using HNSW index (150x-12,500x faster than keyword search)',
+        description: 'Find stored memories by meaning (vector similarity), not by literal text — finds "JWT auth pattern" when you query "token-based login flow". Use when native Grep is wrong because Grep matches characters and you need to find conceptually-related entries across past sessions. Backed by HNSW index over ONNX embeddings; returns top-k with similarity scores. Pair with smart=true for query expansion + MMR diversity.',
         category: 'memory',
         inputSchema: {
             type: 'object',
@@ -404,7 +404,7 @@ export const memoryTools = [
     },
     {
         name: 'memory_delete',
-        description: 'Delete a memory entry by key',
+        description: 'Remove a stored memory entry by exact (namespace, key). Use when a previously stored decision is invalidated or contains stale data. No native equivalent — Write to a file does not affect the .swarm/memory.db SQLite store.',
         category: 'memory',
         inputSchema: {
             type: 'object',
@@ -444,7 +444,7 @@ export const memoryTools = [
     },
     {
         name: 'memory_list',
-        description: 'List memory entries with optional filtering',
+        description: 'Enumerate stored memory entries (optionally filtered by namespace/tags) without semantic search. Use when native Glob is wrong because the entries are not files (they live in .swarm/memory.db). For inspection / audit / "what is in my memory" — pair with memory_search for retrieval-by-meaning.',
         category: 'memory',
         inputSchema: {
             type: 'object',

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

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.6.28",
+  "version": "3.6.30",
   "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",