π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
Checkpoint: File edits
rUv0d7726da8412
diff --git a/CLAUDE.md b/CLAUDE.mdindex 6f1d834071..423c1ac400 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,105 +1,636 @@-# Claude Flow V3 β Agent Constitution+# Claude Code Configuration - Claude Flow V3## Behavioral Rules (Always Enforced)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.+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.## File Organization-NEVER save to the root folder. Use these directories:-- `/src` β Source code+**NEVER save to root folder. Use these directories:**+- `/src` β Source code files- `/tests` β Test files-- `/docs` β Documentation (only when requested)-- `/config` β Configuration+- `/docs` β Documentation and markdown files+- `/config` β Configuration files- `/scripts` β Utility scripts- `/examples` β Example code-## Concurrency Rule+## Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS-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+ALL operations MUST be concurrent/parallel in a single message. USE CLAUDE CODE'S TASK TOOL for spawning agents, not just MCP.-## Swarm Orchestration+**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-**Auto-invoke swarm when task involves 3+ files, new features, cross-module refactoring, API changes with tests, security changes, or performance optimization.**+----Skip swarm for: single file edits, 1-2 line fixes, doc updates, config changes, questions.+## Automatic Swarm Orchestration-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+**When starting work on complex tasks, Claude Code MUST automatically:**-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 |+1. **Initialize the swarm** using MCP tools+2. **Spawn concurrent agents** using Claude Code's Task tool+3. **Coordinate via hooks** and memory-## Model Routing (3-Tier)+### CRITICAL: MCP + Task Tool in SAME Message-| 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 |+**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-Check for `[AGENT_BOOSTER_AVAILABLE]` or `[TASK_MODEL_RECOMMENDATION]` before spawning agents.+**MCP alone does NOT execute work β Task tool agents do the actual work!**++### Intelligent 3-Tier Model Routing (ADR-026)++| 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]` β 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+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)++**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+})+```++| 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)+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()})+})+```++### Agent Routing (Anti-Drift)++| 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 |++**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-- **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/`)+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-## Key CLI 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-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+# 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`-## MCP Setup+## 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++| 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```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+```++## 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++| 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++```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 serversclaude 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+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++**KEY**: MCP coordinates the strategy, Claude Code's Task tool executes with real agents.+## 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++```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-Tags that MUST be updated: `@claude-flow/cli` (alpha, latest), `claude-flow` (alpha, latest, v3alpha).+# STEP 2: Publish umbrella+cd /workspaces/claude-flow+npm version 3.0.0-alpha.YYY --no-git-tag-version+npm publish --tag v3alpha++# STEP 3: Update ALL umbrella tags (CRITICAL - DON'T SKIP!)+npm dist-tag add [email protected] latest+npm dist-tag add [email protected] alpha+```++**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'+```-The umbrella `alpha` tag is most commonly forgotten β users run `npx claude-flow@alpha`.+## Support-## Claude Code vs MCP/CLI+- Documentation: https://github.com/ruvnet/claude-flow+- Issues: https://github.com/ruvnet/claude-flow/issues-- **Claude Code** executes: Task tool agents, file ops, code generation, Bash, git-- **MCP/CLI** coordinates: swarm init, agent types, task orchestration, memory, hooks+----**KEY**: MCP coordinates strategy, Claude Code's Task tool executes with real agents.+Remember: **Claude Flow coordinates, Claude Code creates!**diff --git a/agents/architect.yaml b/agents/architect.yamlindex a1ee732553..4b7bf4af0a 100644--- a/agents/architect.yaml+++ b/agents/architect.yaml@@ -8,4 +8,4 @@ capabilities:optimizations:- context-caching- memory-persistence-createdAt: "2026-02-02T04:22:16.648Z"+createdAt: "2026-02-02T04:24:59.852Z"diff --git a/agents/coder.yaml b/agents/coder.yamlindex 586df1a39c..9039a0f96c 100644--- a/agents/coder.yaml+++ b/agents/coder.yaml@@ -8,4 +8,4 @@ capabilities:optimizations:- flash-attention- token-reduction-createdAt: "2026-02-02T04:22:16.648Z"+createdAt: "2026-02-02T04:24:59.851Z"diff --git a/agents/reviewer.yaml b/agents/reviewer.yamlindex a184969521..9f9d89e1aa 100644--- a/agents/reviewer.yaml+++ b/agents/reviewer.yaml@@ -7,4 +7,4 @@ capabilities:- best-practicesoptimizations:- incremental-analysis-createdAt: "2026-02-02T04:22:16.649Z"+createdAt: "2026-02-02T04:24:59.852Z"diff --git a/agents/security-architect.yaml b/agents/security-architect.yamlindex a933297c5f..4aed6963ac 100644--- a/agents/security-architect.yaml+++ b/agents/security-architect.yaml@@ -7,4 +7,4 @@ capabilities:- security-reviewoptimizations:- pattern-matching-createdAt: "2026-02-02T04:22:16.649Z"+createdAt: "2026-02-02T04:24:59.852Z"diff --git a/agents/tester.yaml b/agents/tester.yamlindex 45c019e26d..73679983a0 100644--- a/agents/tester.yaml+++ b/agents/tester.yaml@@ -7,4 +7,4 @@ capabilities:- coverageoptimizations:- parallel-execution-createdAt: "2026-02-02T04:22:16.649Z"+createdAt: "2026-02-02T04:24:59.852Z"