@claude-flow/cli 3.0.0-alpha.9 → 3.0.0-alpha.90

package/README.md

@@ -5,19 +5,20 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
-[![Commands](https://img.shields.io/badge/Commands-14+-orange.svg)](https://github.com/ruvnet/claude-flow)
-[![Subcommands](https://img.shields.io/badge/Subcommands-92+-purple.svg)](https://github.com/ruvnet/claude-flow)
+[![Commands](https://img.shields.io/badge/Commands-29-orange.svg)](https://github.com/ruvnet/claude-flow)
+[![Subcommands](https://img.shields.io/badge/Subcommands-170+-purple.svg)](https://github.com/ruvnet/claude-flow)
 
-> Modern CLI module for Claude Flow V3 - comprehensive command-line interface with 14 commands, 92+ subcommands, interactive prompts, self-learning hooks, background workers, hive-mind coordination, and beautiful output formatting.
+> Modern CLI module for Claude Flow V3 - comprehensive command-line interface with 29 commands, 170+ subcommands, interactive prompts, self-learning hooks, background workers, hive-mind coordination, Q-Learning agent routing, code analysis, collaborative issue claims, smart error suggestions, and beautiful output formatting.
 
 ## Features
 
 ### Core Capabilities
-- **14 Main Commands** - Complete CLI coverage for all Claude Flow operations
-- **92+ Subcommands** - Fine-grained control over every aspect of the system
+- **29 Main Commands** - Complete CLI coverage for all Claude Flow operations
+- **170+ Subcommands** - Fine-grained control over every aspect of the system
 - **Advanced Argument Parsing** - Full support for flags, options, subcommands, and positional arguments
 - **Interactive Prompts** - Rich interactive mode with confirmations, selections, and input validation
 - **Beautiful Output** - Colored output, tables, progress bars, spinners, and multiple formats (text, JSON, table)
+- **Smart Error Suggestions** - Levenshtein distance-based typo detection with helpful corrections
 
 ### V3-Specific Features
 - **Self-Learning Hooks** - 17 hook subcommands + 12 background workers with pattern learning and neural integration
@@ -25,11 +26,15 @@
 - **15-Agent Swarm** - V3 hierarchical mesh coordination with domain specialization
 - **AgentDB Integration** - 150x-12,500x faster vector search with HNSW indexing
 - **SONA Learning** - Sub-0.05ms adaptation with Mixture of Experts routing
+- **Q-Learning Routing** - Intelligent task-to-agent routing with reinforcement learning
+- **Code Analysis** - AST analysis, diff classification, complexity metrics, boundary detection
+- **Issue Claims (ADR-016)** - Collaborative human-agent issue management with work stealing
 
 ### Developer Experience
 - **Type-Safe** - Full TypeScript support with comprehensive type definitions
 - **Global Options** - Built-in `--help`, `--version`, `--verbose`, `--quiet`, `--format`
-- **Auto-Completion** - Shell completion support for commands and options
+- **Shell Completions** - Full tab completion for bash, zsh, fish, and PowerShell
+- **Doctor Command** - System diagnostics with health checks and suggested fixes
 - **Migration Tools** - Built-in V2 to V3 migration with rollback support
 
 ## Installation
@@ -63,6 +68,15 @@ claude-flow swarm init --v3-mode
 # Search memory
 claude-flow memory search -q "authentication patterns"
 
+# Route task to optimal agent (Q-Learning)
+claude-flow route task "Implement OAuth2 authentication"
+
+# Analyze code complexity
+claude-flow analyze complexity ./src
+
+# Claim an issue
+claude-flow issues claim ISSUE-123
+
 # Check system status
 claude-flow status --watch
 ```
@@ -87,6 +101,21 @@ claude-flow status --watch
 | `hooks` | 17 | Self-learning hooks with neural pattern recognition + 12 background workers |
 | `hive-mind` | 6 | Queen-led consensus-based multi-agent coordination |
 | `migrate` | 5 | V2 to V3 migration with rollback support |
+| `process` | 4 | Background process management and monitoring |
+| `daemon` | 5 | Node.js 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` | 13 | Vector embeddings with ONNX models, hyperbolic space, and neural substrate |
+| `claims` | 4 | Claims-based authorization (check, grant, revoke, list) |
+| `issues` | 10 | Collaborative issue claims with work stealing (ADR-016) |
+| `route` | 7 | Q-Learning agent routing with reinforcement learning |
+| `analyze` | 11 | Code analysis (AST, diff, complexity, boundaries, dependencies) |
+| `doctor` | 1 | System diagnostics with health checks and suggested fixes |
+| `completions` | 4 | Shell completions for bash, zsh, fish, and PowerShell |
 
 ---
 
@@ -954,6 +983,501 @@ claude-flow migrate rollback --backup-id backup-1704369600
 
 ---
 
+### `embeddings` - Vector Embeddings
+
+ONNX-based embeddings with hyperbolic space (Poincaré ball), semantic search, and neural substrate integration.
+
+```bash
+claude-flow embeddings <subcommand> [options]
+```
+
+#### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `init` | Initialize ONNX model and hyperbolic configuration |
+| `generate` | Generate embeddings for text |
+| `search` | Semantic similarity search with HNSW |
+| `compare` | Compare similarity between texts |
+| `collections` | Manage embedding collections/namespaces |
+| `index` | Manage HNSW indexes (build, rebuild, optimize) |
+| `providers` | List available embedding providers |
+| `chunk` | Document chunking with configurable overlap |
+| `normalize` | L2/L1/minmax/zscore normalization |
+| `hyperbolic` | Hyperbolic embedding operations (Poincaré ball) |
+| `neural` | Neural substrate features (drift, memory, swarm) |
+| `models` | List and download ONNX models |
+| `cache` | Manage persistent SQLite cache |
+
+#### Supported Models
+
+| Model | Dimensions | Size | Use Case |
+|-------|------------|------|----------|
+| `all-MiniLM-L6-v2` | 384 | 23MB | Fast, general purpose (default) |
+| `all-mpnet-base-v2` | 768 | 110MB | Higher quality, more compute |
+| `bge-small-en-v1.5` | 384 | 33MB | BGE family, good for retrieval |
+
+#### Hyperbolic Embeddings
+
+The Poincaré ball model provides:
+- **Better hierarchical representation** - Exponential capacity in low dimensions
+- **Distance preservation** - Geodesic distance preserves hierarchy
+- **Use cases** - Taxonomies, org charts, file systems, knowledge graphs
+
+#### Examples
+
+```bash
+# Initialize embedding subsystem with defaults
+claude-flow embeddings init
+
+# Use larger model with custom curvature
+claude-flow embeddings init --model all-mpnet-base-v2 --curvature -0.5
+
+# Euclidean only (no hyperbolic)
+claude-flow embeddings init --no-hyperbolic
+
+# Generate embedding
+claude-flow embeddings generate -t "Implement OAuth2 authentication"
+
+# Semantic search
+claude-flow embeddings search -q "authentication patterns" --limit 10
+
+# Compare texts
+claude-flow embeddings compare --text1 "Hello" --text2 "Hi there"
+
+# Document chunking
+claude-flow embeddings chunk -t "Long document..." --max-size 512 --overlap 50
+
+# Hyperbolic operations
+claude-flow embeddings hyperbolic -a convert
+
+# Neural substrate (drift detection, memory physics)
+claude-flow embeddings neural --init
+claude-flow embeddings neural -f drift
+
+# Download model
+claude-flow embeddings models -d all-mpnet-base-v2
+
+# Cache stats
+claude-flow embeddings cache
+```
+
+#### Configuration File
+
+After `embeddings init`, configuration is stored in `.claude-flow/embeddings.json`:
+
+```json
+{
+  "model": "all-MiniLM-L6-v2",
+  "modelPath": ".claude-flow/models",
+  "dimension": 384,
+  "cacheSize": 256,
+  "hyperbolic": {
+    "enabled": true,
+    "curvature": -1,
+    "epsilon": 1e-15,
+    "maxNorm": 0.99999
+  },
+  "neural": {
+    "enabled": true,
+    "driftThreshold": 0.3,
+    "decayRate": 0.01
+  }
+}
+```
+
+---
+
+### `doctor` - System Diagnostics
+
+System health checks with automatic fix suggestions.
+
+```bash
+claude-flow doctor [options]
+```
+
+#### Health Checks
+
+| Check | Description | Auto-Fix |
+|-------|-------------|----------|
+| Node.js Version | Verify Node.js 20+ | nvm install 20 |
+| npm Version | Verify npm 9+ | npm install -g npm@latest |
+| Git | Check git installation | Install git |
+| Git Repository | Check if in git repo | git init |
+| Config File | Validate configuration | claude-flow config init |
+| Daemon Status | Check daemon running | claude-flow daemon start |
+| Memory Database | Check memory DB | claude-flow memory configure |
+| API Keys | Check for API keys | export ANTHROPIC_API_KEY=... |
+| MCP Servers | Check MCP configuration | claude mcp add claude-flow ... |
+| Disk Space | Check available space | Free up disk |
+| TypeScript | Check TypeScript install | npm install -D typescript |
+
+#### Options
+
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
+| `--fix` | `-f` | Show fix commands for issues | `false` |
+| `--component` | `-c` | Check specific component | all |
+| `--verbose` | `-v` | Verbose output | `false` |
+
+#### Examples
+
+```bash
+# Run full health check
+claude-flow doctor
+
+# Show fixes for issues
+claude-flow doctor --fix
+
+# Check specific component
+claude-flow doctor -c daemon
+claude-flow doctor -c mcp
+claude-flow doctor -c memory
+```
+
+#### Output Example
+
+```
+Claude Flow Doctor
+System diagnostics and health check
+──────────────────────────────────────────────────
+
+✓ Node.js Version: v22.21.1 (>= 20 required)
+✓ npm Version: v10.9.4
+✓ Git: v2.52.0
+✓ Git Repository: In a git repository
+⚠ Config File: No config file (using defaults)
+⚠ Daemon Status: Not running
+⚠ Memory Database: Not initialized
+⚠ API Keys: No API keys found
+⚠ MCP Servers: No MCP config found
+✓ Disk Space: 73G available
+✓ TypeScript: v5.9.3
+
+──────────────────────────────────────────────────
+
+Summary: 6 passed, 5 warnings
+
+All checks passed with some warnings.
+```
+
+---
+
+### `route` - Q-Learning Agent Router
+
+Intelligent task-to-agent routing using reinforcement learning.
+
+```bash
+claude-flow route <subcommand> [options]
+```
+
+#### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `task` | Route a task to optimal agent using Q-Learning |
+| `list-agents` | List available agent types with capabilities |
+| `stats` | Show router statistics and learning metrics |
+| `feedback` | Provide routing feedback for continuous learning |
+| `reset` | Reset Q-Learning router state |
+| `export` | Export Q-table for persistence |
+| `import` | Import Q-table from file |
+
+#### Agent Types
+
+| Type | Description |
+|------|-------------|
+| `coder` | Code implementation and debugging |
+| `tester` | Testing and quality assurance |
+| `reviewer` | Code review and quality checks |
+| `architect` | System design and architecture |
+| `researcher` | Research and information gathering |
+| `optimizer` | Performance optimization |
+| `debugger` | Bug fixing and troubleshooting |
+| `documenter` | Documentation and comments |
+
+#### How It Works
+
+1. **State Encoding** - Analyzes task description using hash-based feature extraction
+2. **Q-Learning** - Uses Q-table to map (state, action) pairs to expected rewards
+3. **Epsilon-Greedy** - Balances exploration (try new agents) vs exploitation (use best known)
+4. **Feedback Loop** - Learns from success/failure outcomes to improve routing
+
+#### Examples
+
+```bash
+# Route a task to optimal agent
+claude-flow route task "Implement user authentication with JWT"
+
+# Route with verbose output showing decision process
+claude-flow route task "Fix memory leak in API handler" --verbose
+
+# List available agent types
+claude-flow route list-agents
+
+# View router statistics
+claude-flow route stats
+
+# Provide feedback (reward: -1 to 1)
+claude-flow route feedback --agent coder --reward 0.8 --task "auth implementation"
+
+# Export Q-table for backup
+claude-flow route export -o ./q-table.json
+
+# Import Q-table
+claude-flow route import -i ./q-table.json
+
+# Reset router (start fresh)
+claude-flow route reset --confirm
+```
+
+---
+
+### `analyze` - Code Analysis
+
+Comprehensive code analysis with AST parsing, diff classification, complexity metrics, and dependency analysis.
+
+```bash
+claude-flow analyze <subcommand> [options]
+```
+
+#### Subcommands
+
+| Subcommand | Description | Algorithm |
+|------------|-------------|-----------|
+| `ast` | AST analysis with symbol extraction | tree-sitter (regex fallback) |
+| `complexity` | Cyclomatic and cognitive complexity | McCabe + cognitive metrics |
+| `symbols` | Extract functions, classes, types | AST parsing |
+| `imports` | Import dependency analysis | Static analysis |
+| `diff` | Diff classification and risk assessment | Pattern matching |
+| `boundaries` | Code boundaries detection | MinCut algorithm |
+| `modules` | Module community detection | Louvain algorithm |
+| `dependencies` | Full dependency graph | Graph building |
+| `circular` | Circular dependency detection | Tarjan's SCC |
+| `deps` | Project dependency analysis | npm/yarn |
+| `code` | Static code quality analysis | Multi-metric |
+
+#### Diff Risk Levels
+
+| Risk | Color | Description |
+|------|-------|-------------|
+| `critical` | Red | Breaking changes, security-sensitive |
+| `high` | Orange | Core logic, API changes |
+| `medium` | Yellow | Feature additions, significant refactoring |
+| `low` | Green | Documentation, tests, formatting |
+
+#### Examples
+
+```bash
+# Analyze AST of a file
+claude-flow analyze ast ./src/auth/login.ts
+
+# Analyze with symbol extraction
+claude-flow analyze symbols ./src/services/ --recursive
+
+# Check cyclomatic complexity
+claude-flow analyze complexity ./src --threshold 10
+
+# Classify a git diff
+claude-flow analyze diff HEAD~1
+
+# Classify staged changes
+claude-flow analyze diff --staged
+
+# Find code boundaries (module splits)
+claude-flow analyze boundaries ./src --min-cut
+
+# Detect module communities
+claude-flow analyze modules ./src --algorithm louvain
+
+# Find circular dependencies
+claude-flow analyze circular ./src
+
+# Full dependency graph
+claude-flow analyze dependencies ./src -o ./deps.dot --format dot
+
+# Project dependency analysis
+claude-flow analyze deps --outdated
+```
+
+---
+
+### `issues` - Collaborative Issue Claims (ADR-016)
+
+Human-agent collaborative issue management with work stealing, load balancing, and handoffs.
+
+```bash
+claude-flow issues <subcommand> [options]
+```
+
+#### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List all active claims |
+| `claim` | Claim an issue for yourself or an agent |
+| `release` | Release a claim |
+| `handoff` | Request handoff to another agent/user |
+| `status` | Update claim status and progress |
+| `stealable` | List issues available for work stealing |
+| `steal` | Steal an issue from overloaded/stale claimant |
+| `load` | View agent load distribution |
+| `rebalance` | Rebalance claims across swarm |
+| `board` | Visual Kanban-style claim board |
+
+#### Claim Status
+
+| Status | Description |
+|--------|-------------|
+| `active` | Actively being worked on |
+| `paused` | Temporarily paused |
+| `blocked` | Blocked by dependency |
+| `stealable` | Available for work stealing |
+| `completed` | Work completed |
+| `handoff-pending` | Awaiting handoff acceptance |
+| `review-requested` | Needs review |
+
+#### Work Stealing
+
+Issues can be marked stealable when:
+- **Overloaded** - Claimant has too many active claims
+- **Stale** - No progress for extended period
+- **Blocked** - Blocked beyond timeout threshold
+- **Voluntary** - Claimant voluntarily releases
+
+#### Examples
+
+```bash
+# List all claims
+claude-flow issues list
+
+# List with status filter
+claude-flow issues list --status active
+
+# Claim an issue
+claude-flow issues claim ISSUE-123
+
+# Claim as agent
+claude-flow issues claim ISSUE-123 --as-agent --type coder
+
+# Update progress
+claude-flow issues status ISSUE-123 --progress 50
+
+# Mark as blocked
+claude-flow issues status ISSUE-123 --set blocked --note "Waiting for API"
+
+# Request handoff to another user
+claude-flow issues handoff ISSUE-123 --to user:alice:Alice
+
+# Request handoff to agent
+claude-flow issues handoff ISSUE-123 --to agent:coder:coder-001
+
+# View stealable issues
+claude-flow issues stealable
+
+# Steal an issue
+claude-flow issues steal ISSUE-123 --reason overloaded
+
+# View agent load
+claude-flow issues load
+
+# Rebalance swarm
+claude-flow issues rebalance --strategy even
+
+# Visual board view
+claude-flow issues board
+```
+
+#### Board View
+
+```
+📋 Issue Claims Board
+────────────────────────────────────────────────────────────────
+
+ACTIVE (3)          PAUSED (1)          BLOCKED (1)
+────────────────    ────────────────    ────────────────
+│ ISSUE-123    │    │ ISSUE-456    │    │ ISSUE-789    │
+│ 🤖 coder     │    │ 👤 alice     │    │ 🤖 tester    │
+│ 75% ████░░░  │    │ 30% ██░░░░░  │    │ 50% ███░░░░  │
+└──────────────┘    └──────────────┘    └──────────────┘
+```
+
+---
+
+### `completions` - Shell Completions
+
+Generate shell completion scripts for tab completion of commands.
+
+```bash
+claude-flow completions <shell>
+```
+
+#### Supported Shells
+
+| Shell | Installation | File Location |
+|-------|-------------|---------------|
+| `bash` | `claude-flow completions bash >> ~/.bashrc` | `~/.bash_completion.d/claude-flow` |
+| `zsh` | `claude-flow completions zsh > ~/.zfunc/_claude-flow` | `~/.zfunc/_claude-flow` |
+| `fish` | `claude-flow completions fish > ~/.config/fish/completions/claude-flow.fish` | `~/.config/fish/completions/` |
+| `powershell` | `claude-flow completions powershell >> $PROFILE` | PowerShell profile |
+
+#### Examples
+
+```bash
+# Install bash completions
+claude-flow completions bash > ~/.bash_completion.d/claude-flow
+source ~/.bash_completion.d/claude-flow
+
+# Install zsh completions
+mkdir -p ~/.zfunc
+claude-flow completions zsh > ~/.zfunc/_claude-flow
+# Add to .zshrc: fpath=(~/.zfunc $fpath); autoload -Uz compinit; compinit
+
+# Install fish completions
+claude-flow completions fish > ~/.config/fish/completions/claude-flow.fish
+
+# Install PowerShell completions
+claude-flow completions powershell >> $PROFILE
+```
+
+#### Completion Features
+
+- All 29 top-level commands
+- Full subcommand completion for each command
+- Flag and option completion
+- Dynamic suggestions based on context
+
+---
+
+### Smart Error Suggestions
+
+When you mistype a command, the CLI provides helpful suggestions using Levenshtein distance matching.
+
+```bash
+$ claude-flow swram
+[ERROR] Unknown command: swram
+  Did you mean one of these?
+  - swarm
+  - neural
+  - start
+
+$ claude-flow memroy
+[ERROR] Unknown command: memroy
+  Did you mean "memory"?
+
+$ claude-flow agnet
+[ERROR] Unknown command: agnet
+  Did you mean "agent"?
+```
+
+The suggestion system:
+- Uses Levenshtein distance to find similar commands
+- Recognizes 40+ common typos (e.g., `memroy` → `memory`, `swram` → `swarm`)
+- Suggests up to 3 alternatives sorted by similarity
+- Boosts prefix matches for better suggestions
+
+---
+
 ## Global Options
 
 All commands support these global options:
@@ -1180,6 +1704,9 @@ The CLI is optimized for V3 performance targets:
 - [@claude-flow/mcp](../mcp) - MCP server implementation
 - [@claude-flow/hooks](../hooks) - Self-learning hooks system
 - [@claude-flow/neural](../neural) - SONA neural learning
+- [@claude-flow/embeddings](../embeddings) - Vector embeddings (75x faster with agentic-flow)
+- [@claude-flow/security](../security) - CVE remediation & security patterns
+- [@claude-flow/providers](../providers) - Multi-LLM provider system
 
 ## License