Claude Code Configuration - Ruflo v3.5

Ruflo v3.6 (2026-04-29) — Stable release with agent federation and comms-first coordination. 6,000+ commits, 314 MCP tools, 16 agent roles + custom types, 19 AgentDB controllers, 21 native plugins. Packages: @claude-flow/cli@3.6.10, claude-flow@3.6.10, ruflo@3.6.10

Behavioral Rules (Always Enforced)

• Do what has been asked; nothing more, nothing less
• NEVER create files unless they're absolutely necessary for achieving your goal
• ALWAYS prefer editing an existing file to creating a new one
• NEVER proactively create documentation files (*.md) or README files unless explicitly requested
• NEVER save working files, text/mds, or tests to the root folder
• Never continuously check status after spawning a swarm — wait for results
• ALWAYS read a file before editing it
• NEVER commit secrets, credentials, or .env files

File Organization

• NEVER save to root folder — use the directories below
• Use /src for source code files
• Use /tests for test files
• Use /docs for documentation and markdown files
• Use /config for configuration files
• Use /scripts for utility scripts
• Use /examples for example code

Project Architecture

• Follow Domain-Driven Design with bounded contexts
• Keep files under 500 lines
• Use typed interfaces for all public APIs
• Prefer TDD London School (mock-first) for new code
• Use event sourcing for state changes
• Ensure input validation at system boundaries

Key Packages

Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS

• All operations MUST be concurrent/parallel in a single message
• Use Claude Code's Task tool for spawning agents, not just MCP

Mandatory patterns:

• ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum)
• ALWAYS spawn ALL agents in ONE message with full instructions via Task tool
• ALWAYS batch ALL file reads/writes/edits in ONE message
• ALWAYS batch ALL terminal operations in ONE Bash message
• ALWAYS batch ALL memory store/retrieve operations in ONE message

Swarm Orchestration

• MUST initialize the swarm using MCP tools when starting complex tasks
• MUST spawn concurrent agents using Claude Code's Task tool
• Never use MCP tools alone for execution — Task tool agents do the actual work

MCP + Task Tool in SAME Message

• MUST call MCP tools AND Task tool in ONE message for complex work
• Always call MCP first, then IMMEDIATELY call Task tool to spawn agents

3-Tier Model Routing (ADR-026)

• Always check for [AGENT_BOOSTER_AVAILABLE] or [TASK_MODEL_RECOMMENDATION] before spawning agents
• Use Edit tool directly when [AGENT_BOOSTER_AVAILABLE] — intent types: var-to-const, add-types, add-error-handling, async-await, add-logging, remove-console

Swarm Configuration & Anti-Drift

Anti-Drift Coding Swarm (PREFERRED DEFAULT)

• ALWAYS use hierarchical topology for coding swarms
• Keep maxAgents at 6-8 for tight coordination
• Use specialized strategy for clear role boundaries
• Use raft consensus for hive-mind (leader maintains authoritative state)
• Run frequent checkpoints via post-task hooks
• Keep shared memory namespace for all agents
• Keep task cycles short with verification gates

mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 8,
  strategy: "specialized"
})

Dual-Mode Collaboration (Claude Code + Codex)

This repository uses dual-mode orchestration to run Claude Code (🔵) and OpenAI Codex (🟢) workers in parallel with shared memory coordination. Both platforms collaborate on development tasks with cross-learning.

Why Dual-Mode?

Dual-Mode Swarm Protocol

For complex tasks, spawn both Claude and Codex workers in parallel:

// STEP 1: Initialize dual-mode swarm
mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 8,
  strategy: "specialized"
})

// STEP 2: Spawn BOTH platforms in parallel via Task tool
// 🔵 Claude Code workers (architecture, security, testing)
Task("Architect", "Design the implementation. Store design in memory namespace 'collaboration'.", "system-architect")
Task("Tester", "Write tests based on architect's design. Read from 'collaboration' namespace.", "tester")
Task("Reviewer", "Review code quality and security. Store findings in 'collaboration'.", "reviewer")

// 🟢 Codex workers (implementation, optimization)
// Spawn via CLI for Codex platform
Bash("npx claude-flow-codex dual run --worker 'codex:coder:Implement the solution based on architect design' --namespace collaboration")
Bash("npx claude-flow-codex dual run --worker 'codex:optimizer:Optimize performance based on implementation' --namespace collaboration")

// STEP 3: Coordinate via shared memory
Bash("npx claude-flow@v3alpha memory store --namespace collaboration --key 'task-context' --value '[task description]'")

Collaboration Templates (Pre-Built Pipelines)

Dual-Mode CLI Commands

# Run a collaboration template
npx claude-flow-codex dual run feature --task "Add user authentication with OAuth"
npx claude-flow-codex dual run security --target "./src"
npx claude-flow-codex dual run refactor --target "./src/legacy"

# Custom multi-platform swarm
npx claude-flow-codex dual run \
  --worker "claude:architect:Design the API structure" \
  --worker "codex:coder:Implement REST endpoints" \
  --worker "claude:tester:Write integration tests" \
  --worker "codex:reviewer:Review code quality" \
  --namespace "api-feature"

# Check collaboration status
npx claude-flow-codex dual status

# List available templates
npx claude-flow-codex dual templates

Shared Memory Coordination

All workers share state via the collaboration namespace:

# Store context for cross-platform sharing
npx claude-flow@v3alpha memory store --namespace collaboration --key "design-decisions" --value "..."

# Search for patterns across all workers
npx claude-flow@v3alpha memory search --namespace collaboration --query "authentication patterns"

# Retrieve specific findings
npx claude-flow@v3alpha memory retrieve --namespace collaboration --key "security-findings"

Cross-Platform Learning

Both platforms learn from each other's outputs:

# After successful collaboration, train patterns
npx claude-flow@v3alpha hooks post-task --task-id "dual-[id]" --success true --train-neural true

# Store successful collaboration patterns
npx claude-flow@v3alpha memory store --namespace patterns --key "dual-mode-[pattern]" --value "[what worked]"

# Transfer learnings to both platforms
npx claude-flow@v3alpha hooks transfer store --pattern "dual-collab-success"

Worker Dependency Levels

Workers execute in dependency order:

Level 0: [🔵 Architect]           # No dependencies - runs first
Level 1: [🟢 Coder, 🔵 Tester]    # Depends on Architect
Level 2: [🔵 Reviewer]            # Depends on Coder + Tester
Level 3: [🟢 Optimizer]           # Depends on Reviewer approval

Platform Strengths

Programmatic API

import { DualModeOrchestrator, CollaborationTemplates } from '@claude-flow/codex';

const orchestrator = new DualModeOrchestrator({
  namespace: 'my-feature',
  memoryBackend: 'hybrid'
});

// Use pre-built template
const workers = CollaborationTemplates.featureDevelopment('Add OAuth login');

// Run collaboration
const results = await orchestrator.runCollaboration(workers, 'Implement OAuth feature');

// Access shared memory
const designDocs = await orchestrator.getMemory('design-decisions');

Swarm Protocols & Routing

Auto-Start Swarm Protocol

When the user requests a complex task (multi-file changes, feature implementation, refactoring), immediately execute this pattern in a SINGLE message:

// STEP 1: Initialize swarm coordination via MCP
mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 8,
  strategy: "specialized"
})

// STEP 2: Spawn NAMED agents concurrently — all in ONE message
// Each agent knows WHO to message next in the pipeline
Task({
  prompt: "Research requirements and codebase. SendMessage findings to 'architect' when done.",
  subagent_type: "researcher", name: "researcher", run_in_background: true
})
Task({
  prompt: "Wait for research from 'researcher'. Design implementation. SendMessage design to 'coder'.",
  subagent_type: "system-architect", name: "architect", run_in_background: true
})
Task({
  prompt: "Wait for design from 'architect'. Implement the solution. SendMessage code paths to 'tester'.",
  subagent_type: "coder", name: "coder", run_in_background: true
})
Task({
  prompt: "Wait for implementation from 'coder'. Write tests. SendMessage results to 'reviewer'.",
  subagent_type: "tester", name: "tester", run_in_background: true
})
Task({
  prompt: "Wait for test results from 'tester'. Review code quality and security. Report findings.",
  subagent_type: "reviewer", name: "reviewer", run_in_background: true
})

// STEP 3: Kick off the pipeline
SendMessage({ to: "researcher", summary: "Start research", message: "[task description and context]" })

// STEP 4: Batch todos
TodoWrite({ todos: [
  {content: "Research and analyze requirements", status: "in_progress", activeForm: "Researching"},
  {content: "Design architecture", status: "pending", activeForm: "Designing"},
  {content: "Implement solution", status: "pending", activeForm: "Implementing"},
  {content: "Write tests", status: "pending", activeForm: "Testing"},
  {content: "Review and finalize", status: "pending", activeForm: "Reviewing"}
]})

// Pipeline flow via SendMessage:
// researcher ──→ architect ──→ coder ──→ tester ──→ reviewer

Agent Routing (Anti-Drift)

Codes 1-11: hierarchical/specialized (anti-drift). Code 13: mesh/balanced

Task Complexity Detection

AUTO-INVOKE SWARM when task involves:

• Multiple files (3+)
• New feature implementation
• Refactoring across modules
• API changes with tests
• Security-related changes
• Performance optimization
• Database schema changes

SKIP SWARM for:

• Single file edits
• Simple bug fixes (1-2 lines)
• Documentation updates
• Configuration changes
• Quick questions/exploration

Project Configuration

This project is configured with Claude Flow V3 (Anti-Drift Defaults):

• Topology: hierarchical (prevents drift via central coordination)
• Max Agents: 8 (smaller team = less drift)
• Strategy: specialized (clear roles, no overlap)
• Consensus: raft (leader maintains authoritative state)
• Memory Backend: hybrid (SQLite + AgentDB)
• HNSW Indexing: Enabled (150x-12,500x faster)
• Neural Learning: Enabled (SONA)

V3 CLI Commands (26 Commands, 140+ Subcommands)

Core Commands

Advanced Commands

Quick CLI Examples

# Initialize project
npx claude-flow@v3alpha init --wizard

# Start daemon with background workers
npx claude-flow@v3alpha daemon start

# Spawn an agent
npx claude-flow@v3alpha agent spawn -t coder --name my-coder

# Initialize swarm
npx claude-flow@v3alpha swarm init --v3-mode

# Search memory (HNSW-indexed)
npx claude-flow@v3alpha memory search -q "authentication patterns"

# System diagnostics
npx claude-flow@v3alpha doctor --fix

# Security scan
npx claude-flow@v3alpha security scan --depth full

# Performance benchmark
npx claude-flow@v3alpha performance benchmark --suite all

Headless Background Instances (claude -p)

Use claude -p (print/pipe mode) to spawn headless Claude instances for parallel background work. These run non-interactively and return results to stdout.

Basic Usage

# Single headless task
claude -p "Analyze the authentication module for security issues"

# With model selection
claude -p --model haiku "Format this config file"
claude -p --model opus "Design the database schema for user management"

# With output format
claude -p --output-format json "List all TODO comments in src/"
claude -p --output-format stream-json "Refactor the error handling in api.ts"

# With budget limits
claude -p --max-budget-usd 0.50 "Run comprehensive security audit"

# With specific tools allowed
claude -p --allowedTools "Read,Grep,Glob" "Find all files that import the auth module"

# Skip permissions (sandboxed environments only)
claude -p --dangerously-skip-permissions "Fix all lint errors in src/"

Parallel Background Execution

# Spawn multiple headless instances in parallel
claude -p "Analyze src/auth/ for vulnerabilities" &
claude -p "Write tests for src/api/endpoints.ts" &
claude -p "Review src/models/ for performance issues" &
wait  # Wait for all to complete

# With results captured
SECURITY=$(claude -p "Security audit of auth module" &)
TESTS=$(claude -p "Generate test coverage report" &)
PERF=$(claude -p "Profile memory usage in workers" &)
wait
echo "$SECURITY" "$TESTS" "$PERF"

Session Continuation

# Start a task, resume later
claude -p --session-id "abc-123" "Start analyzing the codebase"
claude -p --resume "abc-123" "Continue with the test files"

# Fork a session for parallel exploration
claude -p --resume "abc-123" --fork-session "Try approach A: event sourcing"
claude -p --resume "abc-123" --fork-session "Try approach B: CQRS pattern"

Key Flags

Available Agents (60+ Types)

Core Development

coder, reviewer, tester, planner, researcher

V3 Specialized Agents

security-architect, security-auditor, memory-specialist, performance-engineer

@claude-flow/security Module

CVE remediation, input validation, path security:

• InputValidator — Zod-based validation at boundaries
• PathValidator — Path traversal prevention
• SafeExecutor — Command injection protection
• PasswordHasher — bcrypt hashing
• TokenGenerator — Secure token generation

Token Optimizer (Agent Booster)

Integrates agentic-flow optimizations for 30-50% token reduction:

import { getTokenOptimizer } from '@claude-flow/integration';
const optimizer = await getTokenOptimizer();

// Compact context (32% fewer tokens)
const ctx = await optimizer.getCompactContext("auth patterns");

// 352x faster edits = fewer retries
await optimizer.optimizedEdit(file, old, new, "typescript");

// Optimal config (100% success rate)
const config = optimizer.getOptimalConfig(agentCount);

Swarm Coordination

hierarchical-coordinator, mesh-coordinator, adaptive-coordinator, collective-intelligence-coordinator, swarm-memory-manager

Consensus & Distributed

byzantine-coordinator, raft-manager, gossip-coordinator, consensus-builder, crdt-synchronizer, quorum-manager, security-manager

Performance & Optimization

perf-analyzer, performance-benchmarker, task-orchestrator, memory-coordinator, smart-agent

GitHub & Repository

github-modes, pr-manager, code-review-swarm, issue-tracker, release-manager, workflow-automation, project-board-sync, repo-architect, multi-repo-swarm

SPARC Methodology

sparc-coord, sparc-coder, specification, pseudocode, architecture, refinement

Specialized Development

backend-dev, mobile-dev, ml-developer, cicd-engineer, api-docs, system-architect, code-analyzer, base-template-generator

Testing & Validation

tdd-london-swarm, production-validator

Agent Teams & Comms System

Agent Teams turns Claude Code into a multi-agent system where named agents communicate in real-time via SendMessage. The comms system is the primary coordination mechanism — agents talk to each other, not just to the lead.

Architecture

Team Lead (you)
  ├── SendMessage ←→ architect (named agent)
  ├── SendMessage ←→ developer (named agent)
  ├── SendMessage ←→ tester (named agent)
  └── SendMessage ←→ reviewer (named agent)
       ↕ agents can message each other by name

Core Principle: Named Agents + SendMessage

Every agent MUST have a name so it's addressable. Communication happens via SendMessage, not polling or shared memory.

// STEP 1: Spawn named agents (all in ONE message, background)
Task({
  prompt: "Design the API. When done, send your design to 'developer' via SendMessage.",
  subagent_type: "system-architect",
  name: "architect",
  run_in_background: true
})
Task({
  prompt: "Wait for architect's design via SendMessage. Then implement it. Send code to 'tester'.",
  subagent_type: "coder",
  name: "developer",
  run_in_background: true
})
Task({
  prompt: "Wait for developer's code via SendMessage. Write tests. Send results to 'reviewer'.",
  subagent_type: "tester",
  name: "tester",
  run_in_background: true
})

// STEP 2: Kick off the pipeline by messaging the first agent
SendMessage({
  to: "architect",
  summary: "Start API design",
  message: "Design a REST API for user management with CRUD endpoints. Send the design to 'developer' when done."
})

SendMessage Protocol

// Lead → Teammate: assign work
SendMessage({ to: "developer", summary: "Implement auth", message: "Build OAuth2 flow..." })

// Lead → Teammate: redirect priorities
SendMessage({ to: "developer", summary: "Prioritize auth", message: "Auth endpoint is blocking tester, do it first." })

// Lead → Teammate: provide context from another agent's results
SendMessage({ to: "tester", summary: "Architect output", message: "The architect designed these endpoints: [details]. Write tests for them." })

// Lead → Teammate: graceful shutdown
SendMessage({ to: "developer", message: { type: "shutdown_request" } })

Coordination Patterns

Pipeline (A → B → C) — each agent messages the next when done:

architect ──SendMessage──→ developer ──SendMessage──→ tester ──SendMessage──→ reviewer

Tell each agent WHO to message next in their prompt.

Fan-out / Fan-in — lead spawns parallel agents, collects results:

         ┌→ researcher-1 ──→┐
lead ────┼→ researcher-2 ──→├──→ lead synthesizes
         └→ researcher-3 ──→┘

Spawn with run_in_background: true. Results arrive as task completions.

Supervisor / Worker — lead assigns, workers report back:

lead ←──SendMessage──→ worker-1
lead ←──SendMessage──→ worker-2
lead ←──SendMessage──→ worker-3

Lead sends tasks via SendMessage, workers respond with results.

Agent Prompt Template (Comms-Aware)

When spawning agents that need to coordinate, include comms instructions:

Task({
  prompt: `You are the architect for this feature team.

YOUR TASK: Design the database schema for user management.

COMMS PROTOCOL:
- When your design is ready, send it to "developer" via SendMessage
- If you need clarification, message the team lead (just output text)
- Include file paths and key decisions in your message

DELIVERABLE: Schema design with entity relationships, indexes, and migration plan.`,
  subagent_type: "system-architect",
  name: "architect",
  run_in_background: true
})

Full Team Spawn Example

// Create shared task list first
TaskCreate({ subject: "Design schema", description: "...", activeForm: "Designing" })
TaskCreate({ subject: "Implement models", description: "...", activeForm: "Implementing" })
TaskCreate({ subject: "Write tests", description: "...", activeForm: "Testing" })
TaskCreate({ subject: "Security review", description: "...", activeForm: "Reviewing" })

// Spawn ALL named agents in ONE message
Task({
  prompt: "Design the schema. SendMessage to 'developer' with your design when done. Update task #1.",
  subagent_type: "system-architect", name: "architect", run_in_background: true
})
Task({
  prompt: "Wait for schema from 'architect'. Implement models + endpoints. SendMessage to 'tester'. Update task #2.",
  subagent_type: "coder", name: "developer", run_in_background: true
})
Task({
  prompt: "Wait for code from 'developer'. Write integration tests. SendMessage results to 'security'. Update task #3.",
  subagent_type: "tester", name: "tester", run_in_background: true
})
Task({
  prompt: "Wait for test results from 'tester'. Review for vulnerabilities. Update task #4.",
  subagent_type: "security-auditor", name: "security", run_in_background: true
})

Agent Teams Hooks

npx claude-flow@v3alpha hooks teammate-idle --auto-assign true
npx claude-flow@v3alpha hooks task-completed -i task-123 --train-patterns true

Rules

1. Always name agents — use name: "role-name" so they're addressable
2. Comms over memory — use SendMessage for real-time coordination, memory for persistence
3. Pipeline prompts — tell each agent WHO to message next and WHAT to send
4. Spawn all at once — all Task calls in ONE message with run_in_background: true
5. Don't poll — agents message back when done; wait for task completion notifications
6. Graceful shutdown — send { type: "shutdown_request" } before TeamDelete
7. Lead synthesizes — when agents complete, review ALL results before responding to user

V3 Hooks System (17 Hooks + 12 Workers)

Hook Categories

12 Background Workers

Essential Hook Commands

# Core hooks
npx claude-flow@v3alpha hooks pre-task --description "[task]"
npx claude-flow@v3alpha hooks post-task --task-id "[id]" --success true
npx claude-flow@v3alpha hooks post-edit --file "[file]" --train-patterns

# Session management
npx claude-flow@v3alpha hooks session-start --session-id "[id]"
npx claude-flow@v3alpha hooks session-end --export-metrics true
npx claude-flow@v3alpha hooks session-restore --session-id "[id]"

# Intelligence routing
npx claude-flow@v3alpha hooks route --task "[task]"
npx claude-flow@v3alpha hooks explain --topic "[topic]"

# Neural learning
npx claude-flow@v3alpha hooks pretrain --model-type moe --epochs 10
npx claude-flow@v3alpha hooks build-agents --agent-types coder,tester

# Background workers
npx claude-flow@v3alpha hooks worker list
npx claude-flow@v3alpha hooks worker dispatch --trigger audit
npx claude-flow@v3alpha hooks worker status

Intelligence System (RuVector)

V3 includes the RuVector Intelligence System:

• SONA: Self-Optimizing Neural Architecture (<0.05ms adaptation)
• MoE: Mixture of Experts for specialized routing
• HNSW: 150x-12,500x faster pattern search
• EWC++: Elastic Weight Consolidation (prevents forgetting)
• Flash Attention: 2.49x-7.47x speedup

The 4-step intelligence pipeline:

1. RETRIEVE — Fetch relevant patterns via HNSW
2. JUDGE — Evaluate with verdicts (success/failure)
3. DISTILL — Extract key learnings via LoRA
4. CONSOLIDATE — Prevent catastrophic forgetting via EWC++

Embeddings Package (v3.0.0-alpha.12)

Features:

• sql.js: Cross-platform SQLite persistent cache (WASM, no native compilation)
• Document chunking: Configurable overlap and size
• Normalization: L2, L1, min-max, z-score
• Hyperbolic embeddings: Poincare ball model for hierarchical data
• 75x faster: With agentic-flow ONNX integration
• Neural substrate: Integration with RuVector

Hive-Mind Consensus

Topologies

• hierarchical — Queen controls workers directly
• mesh — Fully connected peer network
• hierarchical-mesh — Hybrid (recommended)
• adaptive — Dynamic based on load

Consensus Strategies

• byzantine — BFT (tolerates f < n/3 faulty)
• raft — Leader-based (tolerates f < n/2)
• gossip — Epidemic for eventual consistency
• crdt — Conflict-free replicated data types
• quorum — Configurable quorum-based

V3 Performance Targets

Environment Variables

# Configuration
CLAUDE_FLOW_CONFIG=./claude-flow.config.json
CLAUDE_FLOW_LOG_LEVEL=info

# Provider API Keys
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...

# MCP Server
CLAUDE_FLOW_MCP_PORT=3000
CLAUDE_FLOW_MCP_HOST=localhost
CLAUDE_FLOW_MCP_TRANSPORT=stdio

# Memory
CLAUDE_FLOW_MEMORY_BACKEND=hybrid
CLAUDE_FLOW_MEMORY_PATH=./data/memory

Doctor Health Checks

Run npx claude-flow@v3alpha doctor to check:

• Node.js version (20+)
• npm version (9+)
• Git installation
• Config file validity
• Daemon status
• Memory database
• API keys
• MCP servers
• Disk space
• TypeScript installation

Quick Setup

# Add MCP servers
claude mcp add claude-flow npx claude-flow@v3alpha mcp start
claude mcp add ruv-swarm npx ruv-swarm mcp start  # Optional
claude mcp add flow-nexus npx flow-nexus@latest mcp start  # Optional

# Start daemon
npx claude-flow@v3alpha daemon start

# Run doctor
npx claude-flow@v3alpha doctor --fix

Claude Code vs MCP Tools

Claude Code Handles ALL EXECUTION:

• Task tool: Spawn and run agents concurrently
• File operations (Read, Write, Edit, MultiEdit, Glob, Grep)
• Code generation and programming
• Bash commands and system operations
• TodoWrite and task management
• Git operations

MCP Tools ONLY COORDINATE:

• Swarm initialization (topology setup)
• Agent type definitions
• Task orchestration
• Memory management
• Neural features
• Performance tracking
• Keep MCP for coordination strategy only — use Claude Code's Task tool for real execution

Claude Code ↔ AgentDB Memory Bridge

Claude Code's auto-memory (~/.claude/projects/*/memory/*.md) is bridged to AgentDB with ONNX vector embeddings for semantic search.

MCP Tools

Auto-Import on Session Start

The SessionStart hook automatically imports current project's memories into AgentDB. For manual import of all projects:

# Via MCP tool (from Claude Code)
memory_import_claude({ allProjects: true })

# Via helper hook (from terminal)
node .claude/helpers/auto-memory-hook.mjs import-all

Unified Search

Search across both Claude Code memories and AgentDB entries:

# Via MCP tool
memory_search_unified({ query: "authentication security", limit: 5 })

# Results include source attribution: claude-code, auto-memory, or agentdb

Intelligence Pipeline

Publishing to npm

Publishing Rules

• MUST publish ALL THREE packages when publishing CLI changes: @claude-flow/cli, claude-flow, AND ruflo
• MUST update ALL dist-tags for ALL THREE packages after publishing
• Publish order: @claude-flow/cli first, then claude-flow (umbrella), then ruflo (alias umbrella)
• MUST run verification for ALL THREE before telling user publishing is complete

# STEP 1: Build and publish CLI
cd v3/@claude-flow/cli
npm version 3.0.0-alpha.XXX --no-git-tag-version
npm run build
npm publish --tag alpha
npm dist-tag add @claude-flow/cli@3.0.0-alpha.XXX latest

# STEP 2: Publish claude-flow umbrella
cd /workspaces/claude-flow
npm version 3.0.0-alpha.XXX --no-git-tag-version
npm publish --tag v3alpha

# STEP 3: Update ALL claude-flow umbrella tags (CRITICAL - DON'T SKIP!)
npm dist-tag add claude-flow@3.0.0-alpha.XXX latest
npm dist-tag add claude-flow@3.0.0-alpha.XXX alpha

# STEP 4: Publish ruflo umbrella (CRITICAL - DON'T FORGET!)
cd /workspaces/claude-flow/ruflo
npm version 3.0.0-alpha.XXX --no-git-tag-version
npm publish --tag alpha
npm dist-tag add ruflo@3.0.0-alpha.XXX latest

Verification (run before telling user):

npm view @claude-flow/cli dist-tags --json
npm view claude-flow dist-tags --json
npm view ruflo dist-tags --json
# ALL THREE packages need: alpha AND latest pointing to newest version

All Tags That Must Be Updated

• Never forget the ruflo package — it's a thin wrapper users run via npx ruflo@alpha
• Never forget the umbrella alpha tag — users run npx claude-flow@alpha
• ruflo source is in /ruflo/ — it depends on @claude-flow/cli

Plugin Registry Maintenance (IPFS/Pinata)

The plugin registry is stored on IPFS via Pinata for decentralized, immutable distribution.

Registry Location

• Current CID: Stored in v3/@claude-flow/cli/src/plugins/store/discovery.ts
• Gateway: https://gateway.pinata.cloud/ipfs/{CID}
• Format: JSON with plugin metadata, categories, featured/trending lists

Required Environment Variables

Add to .env (NEVER commit actual values):

PINATA_API_KEY=your-api-key
PINATA_API_SECRET=your-api-secret
PINATA_API_JWT=your-jwt-token

Plugin Registry Operations

Adding a New Plugin to Registry

1. Fetch current registry:

curl -s "https://gateway.pinata.cloud/ipfs/$(grep LIVE_REGISTRY_CID v3/@claude-flow/cli/src/plugins/store/discovery.ts | cut -d"'" -f2)" > /tmp/registry.json

2. Add plugin entry to the plugins array:

{
  "id": "@claude-flow/your-plugin",
  "name": "@claude-flow/your-plugin",
  "displayName": "Your Plugin",
  "description": "Plugin description",
  "version": "1.0.0-alpha.1",
  "size": 100000,
  "checksum": "sha256:abc123",
  "author": {"id": "claude-flow-team", "displayName": "Claude Flow Team", "verified": true},
  "license": "MIT",
  "categories": ["official"],
  "tags": ["your", "tags"],
  "downloads": 0,
  "rating": 5,
  "lastUpdated": "2026-01-25T00:00:00.000Z",
  "minClaudeFlowVersion": "3.0.0",
  "type": "integration",
  "hooks": [],
  "commands": [],
  "permissions": ["memory"],
  "exports": ["YourExport"],
  "verified": true,
  "trustLevel": "official"
}

3. Update counts and arrays:
   • Increment totalPlugins
   • Add to official array
   • Add to featured/newest if applicable
   • Update category pluginCount
4. Upload to Pinata (read credentials from .env):

# Source credentials from .env
PINATA_JWT=$(grep "^PINATA_API_JWT=" .env | cut -d'=' -f2-)

# Upload updated registry
curl -X POST "https://api.pinata.cloud/pinning/pinJSONToIPFS" \
  -H "Authorization: Bearer $PINATA_JWT" \
  -H "Content-Type: application/json" \
  -d @/tmp/registry.json

5. Update discovery.ts with new CID:

export const LIVE_REGISTRY_CID = 'NEW_CID_FROM_PINATA';

6. Also update demo registry in discovery.ts demoPluginRegistry for offline fallback

Security Rules

• NEVER hardcode API keys in scripts or source files
• NEVER commit .env (already in .gitignore)
• Always source credentials from environment at runtime
• Always delete temporary scripts after one-time uploads

Verification

# Verify new registry is accessible
curl -s "https://gateway.pinata.cloud/ipfs/{NEW_CID}" | jq '.totalPlugins'

Optional Plugins (20 Available)

Plugins are distributed via IPFS and can be installed with the CLI. Browse and install from the official registry:

# List all available plugins
npx claude-flow@v3alpha plugins list

# Install a plugin
npx claude-flow@v3alpha plugins install @claude-flow/plugin-name

# Enable/disable
npx claude-flow@v3alpha plugins enable @claude-flow/plugin-name
npx claude-flow@v3alpha plugins disable @claude-flow/plugin-name

Core Plugins

Integration Plugins

Domain-Specific Plugins

Plugin Development

# Create a new plugin from template
npx claude-flow@v3alpha plugins create my-plugin

# Test locally
npx claude-flow@v3alpha plugins install ./path/to/my-plugin

# Publish to registry (requires Pinata credentials)
npx claude-flow@v3alpha plugins publish

Registry source: IPFS via Pinata (QmXbfEAaR7D2Ujm4GAkbwcGZQMHqAMpwDoje4583uNP834)

Support

• Documentation: https://github.com/ruvnet/claude-flow
• Issues: https://github.com/ruvnet/claude-flow/issues

Remember: Claude Flow coordinates, Claude Code creates!