claude-flow 3.6.28 → 3.6.29

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.29",
   "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/package.json

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