Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

Checkpoint: File edits

rUv85102f5f4cbe
diff --git a/CLAUDE.md b/CLAUDE.md
index e7f9351a3e..6f1d834071 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,647 +1,105 @@
-# Claude Code Configuration - Claude Flow V3
+# Claude Flow V3 β€” Agent Constitution
-## 🚨 AUTOMATIC SWARM ORCHESTRATION
+## Behavioral Rules (Always Enforced)
-**When starting work on complex tasks, Claude Code MUST automatically:**
-
-1. **Initialize the swarm** using MCP tools
-2. **Spawn concurrent agents** using Claude Code's Task tool
-3. **Coordinate via hooks** and memory
-
-### 🚨 CRITICAL: MCP + Task Tool in SAME Message
-
-**When user says "spawn swarm" or requests complex work, Claude Code MUST in ONE message:**
-1. Call MCP tools to initialize coordination
-2. **IMMEDIATELY** call Task tool to spawn REAL working agents
-3. Both MCP and Task calls must be in the SAME response
-
-**MCP alone does NOT execute work - Task tool agents do the actual work!**
-
-### πŸ€– INTELLIGENT 3-TIER MODEL ROUTING (ADR-026)
-
-**The routing system has 3 tiers for optimal cost/performance:**
-
-| Tier | Handler | Latency | Cost | Use Cases |
-|------|---------|---------|------|-----------|
-| **1** | Agent Booster (WASM) | <1ms | $0 | Simple transforms (var→const, add types, etc.) - **Skip LLM entirely** |
-| **2** | Haiku | ~500ms | $0.0002 | Simple tasks, low complexity (<30%) |
-| **3** | Sonnet/Opus | 2-5s | $0.003-0.015 | Complex reasoning, architecture, security (>30%) |
-
-**When you see these recommendations:**
-
-1. `[AGENT_BOOSTER_AVAILABLE]` β†’ The task can be handled by Agent Booster (352x faster, $0)
- - Use the Edit tool directly for simple code transforms
- - Intent types: `var-to-const`, `add-types`, `add-error-handling`, `async-await`, `add-logging`, `remove-console`
-
-2. `[TASK_MODEL_RECOMMENDATION] Use model="X"` β†’ Use that model in Task tool:
-```javascript
-// If hook recommends: [TASK_MODEL_RECOMMENDATION] Use model="opus"
-Task({
- prompt: "...",
- subagent_type: "coder",
- model: "opus" // ← USE THE RECOMMENDED MODEL
-})
-```
-
-**Model Selection Logic:**
-| Complexity | Model | Use For |
-|------------|-------|---------|
-| Agent Booster intent detected | **Skip LLM** | var→const, add-types, remove-console (352x faster) |
-| High (architecture, system design, security) | **opus** | Complex reasoning, multi-step planning |
-| Medium (features, refactoring, debugging) | **sonnet** | Balanced capability and speed |
-| Low (formatting, simple fixes, docs) | **haiku** | Fast, cost-effective tasks |
-
-**CRITICAL:** Always check for `[AGENT_BOOSTER_AVAILABLE]` or `[TASK_MODEL_RECOMMENDATION]` before spawning agents.
-
-### πŸ›‘οΈ Anti-Drift Coding Swarm (PREFERRED DEFAULT)
-
-**To prevent goal drift, context drift, and agent desynchronization, ALWAYS use this configuration for coding swarms:**
-
-```javascript
-mcp__ruv-swarm__swarm_init({
- topology: "hierarchical", // Single coordinator enforces alignment
- maxAgents: 8, // Smaller team = less drift surface
- strategy: "specialized" // Clear roles reduce ambiguity
-})
-```
-
-**Why This Prevents Drift:**
-| Choice | Anti-Drift Benefit |
-|--------|-------------------|
-| **hierarchical** | Coordinator validates each output against goal, catches divergence early |
-| **maxAgents: 6-8** | Fewer agents = less coordination overhead, easier alignment |
-| **specialized** | Clear boundaries - each agent knows exactly what to do, no overlap |
-
-**Consensus for Hive-Mind:** Use `raft` (leader maintains authoritative state)
-
-**Additional Anti-Drift Measures:**
-- Frequent checkpoints via `post-task` hooks
-- Shared memory namespace for all agents
-- Short task cycles with verification gates
-
----
-
-### πŸ”„ 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:**
-
-```javascript
-// STEP 1: Initialize swarm coordination via MCP (in parallel with agent spawning)
-// USE ANTI-DRIFT CONFIG: hierarchical + specialized + small team
-mcp__ruv-swarm__swarm_init({
- topology: "hierarchical",
- maxAgents: 8,
- strategy: "specialized"
-})
-
-// STEP 2: Spawn agents concurrently using Claude Code's Task tool
-// ALL Task calls MUST be in the SAME message for parallel execution
-Task("Coordinator", "You are the swarm coordinator. Initialize session, coordinate other agents via memory. Run: npx claude-flow@v3alpha hooks session-start", "hierarchical-coordinator")
-Task("Researcher", "Analyze requirements and existing code patterns. Store findings in memory via hooks.", "researcher")
-Task("Architect", "Design implementation approach based on research. Document decisions in memory.", "system-architect")
-Task("Coder", "Implement the solution following architect's design. Coordinate via hooks.", "coder")
-Task("Tester", "Write tests for the implementation. Report coverage via hooks.", "tester")
-Task("Reviewer", "Review code quality and security. Document findings.", "reviewer")
-
-// STEP 3: Batch all todos
-TodoWrite({ todos: [
- {content: "Initialize swarm coordination", status: "in_progress", activeForm: "Initializing swarm"},
- {content: "Research and analyze requirements", status: "in_progress", activeForm: "Researching requirements"},
- {content: "Design architecture", status: "pending", activeForm: "Designing architecture"},
- {content: "Implement solution", status: "pending", activeForm: "Implementing solution"},
- {content: "Write tests", status: "pending", activeForm: "Writing tests"},
- {content: "Review and finalize", status: "pending", activeForm: "Reviewing code"}
-]})
-
-// STEP 4: Store swarm state in memory
-mcp__claude-flow__memory_usage({
- action: "store",
- namespace: "swarm",
- key: "current-session",
- value: JSON.stringify({task: "[user's task]", agents: 6, startedAt: new Date().toISOString()})
-})
-```
+Do what has been asked; nothing more, nothing less.
+NEVER create files unless absolutely necessary. ALWAYS prefer editing existing files.
+NEVER proactively create documentation files (*.md) or README files unless explicitly requested.
+NEVER save working files, text, markdown, or tests to the root folder.
+After spawning a swarm, wait for results. Do not continuously check status.
-### πŸ“‹ Agent Routing (Anti-Drift)
+## File Organization
-| Code | Task | Agents |
-|------|------|--------|
-| 1 | Bug Fix | coordinator, researcher, coder, tester |
-| 3 | Feature | coordinator, architect, coder, tester, reviewer |
-| 5 | Refactor | coordinator, architect, coder, reviewer |
-| 7 | Performance | coordinator, perf-engineer, coder |
-| 9 | Security | coordinator, security-architect, auditor |
-| 11 | Memory | coordinator, memory-specialist, perf-engineer |
-| 13 | Docs | researcher, api-docs |
+NEVER save to the root folder. Use these directories:
+- `/src` β€” Source code
+- `/tests` β€” Test files
+- `/docs` β€” Documentation (only when requested)
+- `/config` β€” Configuration
+- `/scripts` β€” Utility scripts
+- `/examples` β€” Example code
-**Codes 1-11: hierarchical/specialized (anti-drift). Code 13: mesh/balanced**
+## Concurrency Rule
-### 🎯 Task Complexity Detection
+ALL related operations MUST be batched in a SINGLE message:
+- Multiple file reads/writes/edits β†’ one message
+- Multiple Bash commands β†’ one message
+- Multiple Task tool agent spawns β†’ one message
+- TodoWrite with all items β†’ one call
-**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
+## Swarm Orchestration
-**SKIP SWARM for:**
-- Single file edits
-- Simple bug fixes (1-2 lines)
-- Documentation updates
-- Configuration changes
-- Quick questions/exploration
+**Auto-invoke swarm when task involves 3+ files, new features, cross-module refactoring, API changes with tests, security changes, or performance optimization.**
-## 🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT
+Skip swarm for: single file edits, 1-2 line fixes, doc updates, config changes, questions.
-**ABSOLUTE RULES**:
-1. ALL operations MUST be concurrent/parallel in a single message
-2. **NEVER save working files, text/mds and tests to the root folder**
-3. ALWAYS organize files in appropriate subdirectories
-4. **USE CLAUDE CODE'S TASK TOOL** for spawning agents concurrently, not just MCP
+When spawning a swarm, use in ONE message:
+1. MCP/CLI to initialize coordination (hierarchical topology, max 8 agents, specialized strategy)
+2. Task tool to spawn real working agents in parallel
+3. MCP coordinates strategy; Task tool agents execute work
-### ⚑ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"
+Agent routing by task type:
+| Task | Agents | Topology |
+|------|--------|----------|
+| Bug fix | researcher, coder, tester | mesh |
+| Feature | coordinator, architect, coder, tester, reviewer | hierarchical |
+| Refactor | architect, coder, reviewer | mesh |
+| Performance | researcher, perf-engineer, coder | hierarchical |
+| Security | coordinator, security-architect, auditor | hierarchical |
-**MANDATORY PATTERNS:**
-- **TodoWrite**: ALWAYS batch ALL todos in ONE call (5-10+ todos minimum)
-- **Task tool (Claude Code)**: ALWAYS spawn ALL agents in ONE message with full instructions
-- **File operations**: ALWAYS batch ALL reads/writes/edits in ONE message
-- **Bash commands**: ALWAYS batch ALL terminal operations in ONE message
-- **Memory operations**: ALWAYS batch ALL memory store/retrieve in ONE message
+## Model Routing (3-Tier)
-### πŸ“ File Organization Rules
+| Complexity | Handler | When |
+|------------|---------|------|
+| Trivial | Agent Booster / Edit tool | var→const, add-types, remove-console (skip LLM) |
+| Low | haiku | Formatting, simple fixes, docs |
+| Medium | sonnet | Features, refactoring, debugging |
+| High | opus | Architecture, system design, security |
-**NEVER save to root folder. Use these directories:**
-- `/src` - Source code files
-- `/tests` - Test files
-- `/docs` - Documentation and markdown files
-- `/config` - Configuration files
-- `/scripts` - Utility scripts
-- `/examples` - Example code
+Check for `[AGENT_BOOSTER_AVAILABLE]` or `[TASK_MODEL_RECOMMENDATION]` before spawning agents.
## 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
-
-| Command | Subcommands | Description |
-|---------|-------------|-------------|
-| `init` | 4 | Project initialization with wizard, presets, skills, hooks |
-| `agent` | 8 | Agent lifecycle (spawn, list, status, stop, metrics, pool, health, logs) |
-| `swarm` | 6 | Multi-agent swarm coordination and orchestration |
-| `memory` | 11 | AgentDB memory with vector search (150x-12,500x faster) |
-| `mcp` | 9 | MCP server management and tool execution |
-| `task` | 6 | Task creation, assignment, and lifecycle |
-| `session` | 7 | Session state management and persistence |
-| `config` | 7 | Configuration management and provider setup |
-| `status` | 3 | System status monitoring with watch mode |
-| `start` | 3 | Service startup and quick launch |
-| `workflow` | 6 | Workflow execution and template management |
-| `hooks` | 17 | Self-learning hooks + 12 background workers |
-| `hive-mind` | 6 | Queen-led Byzantine fault-tolerant consensus |
-
-### Advanced Commands
-
-| Command | Subcommands | Description |
-|---------|-------------|-------------|
-| `daemon` | 5 | Background worker daemon (start, stop, status, trigger, enable) |
-| `neural` | 5 | Neural pattern training (train, status, patterns, predict, optimize) |
-| `security` | 6 | Security scanning (scan, audit, cve, threats, validate, report) |
-| `performance` | 5 | Performance profiling (benchmark, profile, metrics, optimize, report) |
-| `providers` | 5 | AI providers (list, add, remove, test, configure) |
-| `plugins` | 5 | Plugin management (list, install, uninstall, enable, disable) |
-| `deployment` | 5 | Deployment management (deploy, rollback, status, environments, release) |
-| `embeddings` | 4 | Vector embeddings (embed, batch, search, init) - 75x faster with agentic-flow |
-| `claims` | 4 | Claims-based authorization (check, grant, revoke, list) |
-| `migrate` | 5 | V2 to V3 migration with rollback support |
-| `process` | 4 | Background process management |
-| `doctor` | 1 | System diagnostics with health checks |
-| `completions` | 4 | Shell completions (bash, zsh, fish, powershell) |
-
-### Quick CLI Examples
-
-```bash
-# 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
-```
-
-## πŸš€ 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:
-```typescript
-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);
-```
-| Feature | Token Savings |
-|---------|---------------|
-| ReasoningBank retrieval | -32% |
-| Agent Booster edits | -15% |
-| Cache (95% hit rate) | -10% |
-| Optimal batch size | -20% |
-
-### 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`
-
-## πŸͺ V3 Hooks System (17 Hooks + 12 Workers)
-
-### Hook Categories
-
-| Category | Hooks | Purpose |
-|----------|-------|---------|
-| **Core** | `pre-edit`, `post-edit`, `pre-command`, `post-command`, `pre-task`, `post-task` | Tool lifecycle |
-| **Session** | `session-start`, `session-end`, `session-restore`, `notify` | Context management |
-| **Intelligence** | `route`, `explain`, `pretrain`, `build-agents`, `transfer` | Neural learning |
-| **Learning** | `intelligence` (trajectory-start/step/end, pattern-store/search, stats, attention) | Reinforcement |
-
-### 12 Background Workers
+- **Monorepo**: Node.js 20+, TypeScript 5.3+, ESM
+- **Topology**: hierarchical (anti-drift)
+- **Consensus**: raft
+- **Memory**: hybrid (SQLite + AgentDB), HNSW-indexed
+- **Packages**: `@claude-flow/cli`, `@claude-flow/guidance`, `@claude-flow/hooks`, `@claude-flow/memory`, `@claude-flow/shared`, `@claude-flow/security`
+- **Governance**: `@claude-flow/guidance` β€” compile, retrieve, enforce, prove, evolve (see `v3/@claude-flow/guidance/`)
-| Worker | Priority | Description |
-|--------|----------|-------------|
-| `ultralearn` | normal | Deep knowledge acquisition |
-| `optimize` | high | Performance optimization |
-| `consolidate` | low | Memory consolidation |
-| `predict` | normal | Predictive preloading |
-| `audit` | critical | Security analysis |
-| `map` | normal | Codebase mapping |
-| `preload` | low | Resource preloading |
-| `deepdive` | normal | Deep code analysis |
-| `document` | normal | Auto-documentation |
-| `refactor` | normal | Refactoring suggestions |
-| `benchmark` | normal | Performance benchmarking |
-| `testgaps` | normal | Test coverage analysis |
-
-### Essential Hook Commands
+## Key CLI Commands
```bash
-# 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
+npx claude-flow@v3alpha init --wizard # Initialize project
+npx claude-flow@v3alpha swarm init --v3-mode # Start swarm
+npx claude-flow@v3alpha agent spawn -t coder # Spawn agent
+npx claude-flow@v3alpha memory search -q "..." # Search memory
+npx claude-flow@v3alpha doctor --fix # Diagnostics
+npx claude-flow@v3alpha security scan # Security scan
```
-## 🧠 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**: PoincarΓ© 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
-
-| Metric | Target | Status |
-|--------|--------|--------|
-| HNSW Search | 150x-12,500x faster | **Implemented** (persistent) |
-| Memory Reduction | 50-75% with quantization | **Implemented** (3.92x Int8) |
-| SONA Integration | Pattern learning | **Implemented** (ReasoningBank) |
-| Flash Attention | 2.49x-7.47x speedup | In progress |
-| MCP Response | <100ms | Achieved |
-| CLI Startup | <500ms | Achieved |
-| SONA Adaptation | <0.05ms | In progress |
-
-## πŸ”§ Environment Variables
+## MCP Setup
```bash
-# 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
-
-```bash
-# 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 mcp add ruv-swarm npx ruv-swarm mcp start # Optional
+claude mcp add flow-nexus npx flow-nexus@latest mcp start # Optional
```
-## 🎯 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
-
-**KEY**: MCP coordinates the strategy, Claude Code's Task tool executes with real agents.
+## Publishing to npm
-## πŸ“¦ Publishing to npm
+**When publishing CLI changes, ALWAYS publish BOTH packages + update ALL tags:**
-### 🚨 CRITICAL: ALWAYS PUBLISH BOTH PACKAGES + UPDATE ALL TAGS
+1. Build and publish `@claude-flow/cli` with `--tag alpha`, then add `latest` tag
+2. Publish `claude-flow` umbrella with `--tag v3alpha`, then add `latest` and `alpha` tags
+3. Verify with `npm view <pkg> dist-tags --json` for BOTH packages
-**When publishing CLI changes, you MUST:**
-1. Publish `@claude-flow/cli`
-2. Publish `claude-flow` (umbrella)
-3. Update ALL dist-tags for BOTH packages
+Tags that MUST be updated: `@claude-flow/cli` (alpha, latest), `claude-flow` (alpha, latest, v3alpha).
-```bash
-# 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/[email protected] latest
+The umbrella `alpha` tag is most commonly forgotten β€” users run `npx claude-flow@alpha`.
-# STEP 2: Publish umbrella
-cd /workspaces/claude-flow
-npm version 3.0.0-alpha.YYY --no-git-tag-version
-npm publish --tag v3alpha
+## Claude Code vs MCP/CLI
-# STEP 3: Update ALL umbrella tags (CRITICAL - DON'T SKIP!)
-npm dist-tag add [email protected] latest
-npm dist-tag add [email protected] alpha
-```
+- **Claude Code** executes: Task tool agents, file ops, code generation, Bash, git
+- **MCP/CLI** coordinates: swarm init, agent types, task orchestration, memory, hooks
-**Verification (MUST DO before telling user):**
-```bash
-npm view @claude-flow/cli dist-tags --json
-npm view claude-flow dist-tags --json
-# BOTH packages need: alpha AND latest pointing to newest version
-```
-
-### All Tags That Must Be Updated
-| Package | Tag | Command Users Run |
-|---------|-----|-------------------|
-| `@claude-flow/cli` | `alpha` | `npx @claude-flow/cli@alpha` |
-| `@claude-flow/cli` | `latest` | `npx @claude-flow/cli@latest` |
-| `claude-flow` | `alpha` | `npx claude-flow@alpha` ⚠️ EASY TO FORGET |
-| `claude-flow` | `latest` | `npx claude-flow@latest` |
-| `claude-flow` | `v3alpha` | `npx claude-flow@v3alpha` |
-
-**The umbrella `alpha` tag is MOST commonly forgotten - users run `npx claude-flow@alpha`!**
-
-## πŸ”Œ 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):
-```bash
-PINATA_API_KEY=your-api-key
-PINATA_API_SECRET=your-api-secret
-PINATA_API_JWT=your-jwt-token
-```
-
-### Adding a New Plugin to Registry
-
-1. **Fetch current registry**:
-```bash
-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:
-```json
-{
- "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):
-```bash
-# 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:
-```typescript
-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
-- **Delete temporary scripts** after one-time uploads
-
-### Verification
-```bash
-# Verify new registry is accessible
-curl -s "https://gateway.pinata.cloud/ipfs/{NEW_CID}" | jq '.totalPlugins'
-```
-
-## Support
-
-- Documentation: https://github.com/ruvnet/claude-flow
-- Issues: https://github.com/ruvnet/claude-flow/issues
-
----
-
-Remember: **Claude Flow coordinates, Claude Code creates!**
-
-# important-instruction-reminders
-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. Only create documentation files if explicitly requested by the User.
-Never save working files, text/mds and tests to the root folder.
-After spawning a swarm, wait, don't continuously check status.
+**KEY**: MCP coordinates strategy, Claude Code's Task tool executes with real agents.
diff --git a/agents/architect.yaml b/agents/architect.yaml
index 0e0b033922..2305fc72e6 100644
--- a/agents/architect.yaml
+++ b/agents/architect.yaml
@@ -8,4 +8,4 @@ capabilities:
optimizations:
- context-caching
- memory-persistence
-createdAt: "2026-01-28T19:24:50.740Z"
+createdAt: "2026-02-02T04:18:39.585Z"
diff --git a/agents/coder.yaml b/agents/coder.yaml
index 116cc061f5..38571e6b36 100644
--- a/agents/coder.yaml
+++ b/agents/coder.yaml
@@ -8,4 +8,4 @@ capabilities:
optimizations:
- flash-attention
- token-reduction
-createdAt: "2026-01-28T19:24:50.740Z"
+createdAt: "2026-02-02T04:18:39.585Z"
diff --git a/agents/reviewer.yaml b/agents/reviewer.yaml
index 13a5cbc7e7..3f4f079654 100644
--- a/agents/reviewer.yaml
+++ b/agents/reviewer.yaml
@@ -7,4 +7,4 @@ capabilities:
- best-practices
optimizations:
- incremental-analysis
-createdAt: "2026-01-28T19:24:50.741Z"
+createdAt: "2026-02-02T04:18:39.586Z"
diff --git a/agents/security-architect.yaml b/agents/security-architect.yaml
index ee8d9f3fc4..f1a9dc8699 100644
--- a/agents/security-architect.yaml
+++ b/agents/security-architect.yaml
@@ -7,4 +7,4 @@ capabilities:
- security-review
optimizations:
- pattern-matching
-createdAt: "2026-01-28T19:24:50.741Z"
+createdAt: "2026-02-02T04:18:39.586Z"
diff --git a/agents/tester.yaml b/agents/tester.yaml
index 40a0608e5a..013348cd6f 100644
--- a/agents/tester.yaml
+++ b/agents/tester.yaml
@@ -7,4 +7,4 @@ capabilities:
- coverage
optimizations:
- parallel-execution
-createdAt: "2026-01-28T19:24:50.741Z"
+createdAt: "2026-02-02T04:18:39.585Z"