docs: Add comprehensive MCP tool improvement plan based on Anthropic best practices

.claude/commands/analysis/bottleneck-detect.md

@@ -0,0 +1,162 @@
+# bottleneck detect
+
+Analyze performance bottlenecks in swarm operations and suggest optimizations.
+
+## Usage
+
+```bash
+npx claude-flow bottleneck detect [options]
+```
+
+## Options
+
+- `--swarm-id, -s <id>` - Analyze specific swarm (default: current)
+- `--time-range, -t <range>` - Analysis period: 1h, 24h, 7d, all (default: 1h)
+- `--threshold <percent>` - Bottleneck threshold percentage (default: 20)
+- `--export, -e <file>` - Export analysis to file
+- `--fix` - Apply automatic optimizations
+
+## Examples
+
+### Basic bottleneck detection
+
+```bash
+npx claude-flow bottleneck detect
+```
+
+### Analyze specific swarm
+
+```bash
+npx claude-flow bottleneck detect --swarm-id swarm-123
+```
+
+### Last 24 hours with export
+
+```bash
+npx claude-flow bottleneck detect -t 24h -e bottlenecks.json
+```
+
+### Auto-fix detected issues
+
+```bash
+npx claude-flow bottleneck detect --fix --threshold 15
+```
+
+## Metrics Analyzed
+
+### Communication Bottlenecks
+
+- Message queue delays
+- Agent response times
+- Coordination overhead
+- Memory access patterns
+
+### Processing Bottlenecks
+
+- Task completion times
+- Agent utilization rates
+- Parallel execution efficiency
+- Resource contention
+
+### Memory Bottlenecks
+
+- Cache hit rates
+- Memory access patterns
+- Storage I/O performance
+- Neural pattern loading
+
+### Network Bottlenecks
+
+- API call latency
+- MCP communication delays
+- External service timeouts
+- Concurrent request limits
+
+## Output Format
+
+```
+🔍 Bottleneck Analysis Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Summary
+├── Time Range: Last 1 hour
+├── Agents Analyzed: 6
+├── Tasks Processed: 42
+└── Critical Issues: 2
+
+🚨 Critical Bottlenecks
+1. Agent Communication (35% impact)
+   └── coordinator → coder-1 messages delayed by 2.3s avg
+
+2. Memory Access (28% impact)
+   └── Neural pattern loading taking 1.8s per access
+
+⚠️ Warning Bottlenecks
+1. Task Queue (18% impact)
+   └── 5 tasks waiting > 10s for assignment
+
+💡 Recommendations
+1. Switch to hierarchical topology (est. 40% improvement)
+2. Enable memory caching (est. 25% improvement)
+3. Increase agent concurrency to 8 (est. 20% improvement)
+
+✅ Quick Fixes Available
+Run with --fix to apply:
+- Enable smart caching
+- Optimize message routing
+- Adjust agent priorities
+```
+
+## Automatic Fixes
+
+When using `--fix`, the following optimizations may be applied:
+
+1. **Topology Optimization**
+
+   - Switch to more efficient topology
+   - Adjust communication patterns
+   - Reduce coordination overhead
+
+2. **Caching Enhancement**
+
+   - Enable memory caching
+   - Optimize cache strategies
+   - Preload common patterns
+
+3. **Concurrency Tuning**
+
+   - Adjust agent counts
+   - Optimize parallel execution
+   - Balance workload distribution
+
+4. **Priority Adjustment**
+   - Reorder task queues
+   - Prioritize critical paths
+   - Reduce wait times
+
+## Performance Impact
+
+Typical improvements after bottleneck resolution:
+
+- **Communication**: 30-50% faster message delivery
+- **Processing**: 20-40% reduced task completion time
+- **Memory**: 40-60% fewer cache misses
+- **Overall**: 25-45% performance improvement
+
+## Integration with Claude Code
+
+```javascript
+// Check for bottlenecks in Claude Code
+mcp__claude-flow__bottleneck_detect {
+  timeRange: "1h",
+  threshold: 20,
+  autoFix: false
+}
+```
+
+## See Also
+
+- `performance report` - Detailed performance analysis
+- `token usage` - Token optimization analysis
+- `swarm monitor` - Real-time monitoring
+- `cache manage` - Cache optimization

.claude/commands/analysis/performance-report.md

@@ -0,0 +1,25 @@
+# performance-report
+
+Generate comprehensive performance reports for swarm operations.
+
+## Usage
+```bash
+npx claude-flow analysis performance-report [options]
+```
+
+## Options
+- `--format <type>` - Report format (json, html, markdown)
+- `--include-metrics` - Include detailed metrics
+- `--compare <id>` - Compare with previous swarm
+
+## Examples
+```bash
+# Generate HTML report
+npx claude-flow analysis performance-report --format html
+
+# Compare swarms
+npx claude-flow analysis performance-report --compare swarm-123
+
+# Full metrics report
+npx claude-flow analysis performance-report --include-metrics --format markdown
+```

.claude/commands/hive-mind/hive-mind-resume.md

@@ -0,0 +1,8 @@
+# hive-mind-resume
+
+Command documentation for hive-mind-resume in category hive-mind.
+
+Usage:
+```bash
+npx claude-flow hive-mind hive-mind-resume [options]
+```

.claude/commands/hive-mind/hive-mind-sessions.md

@@ -0,0 +1,8 @@
+# hive-mind-sessions
+
+Command documentation for hive-mind-sessions in category hive-mind.
+
+Usage:
+```bash
+npx claude-flow hive-mind hive-mind-sessions [options]
+```

.claude/commands/hive-mind/hive-mind-stop.md

@@ -0,0 +1,8 @@
+# hive-mind-stop
+
+Command documentation for hive-mind-stop in category hive-mind.
+
+Usage:
+```bash
+npx claude-flow hive-mind hive-mind-stop [options]
+```

.claude/commands/hive-mind/hive-mind-wizard.md

@@ -0,0 +1,8 @@
+# hive-mind-wizard
+
+Command documentation for hive-mind-wizard in category hive-mind.
+
+Usage:
+```bash
+npx claude-flow hive-mind hive-mind-wizard [options]
+```

.claude/commands/hive-mind/hive-mind.md

@@ -0,0 +1,27 @@
+# hive-mind
+
+Hive Mind collective intelligence system for advanced swarm coordination.
+
+## Usage
+```bash
+npx claude-flow hive-mind [subcommand] [options]
+```
+
+## Subcommands
+- `init` - Initialize hive mind system
+- `spawn` - Spawn hive mind swarm
+- `status` - Show hive mind status
+- `resume` - Resume paused session
+- `stop` - Stop running session
+
+## Examples
+```bash
+# Initialize hive mind
+npx claude-flow hive-mind init
+
+# Spawn swarm
+npx claude-flow hive-mind spawn "Build microservices"
+
+# Check status
+npx claude-flow hive-mind status
+```

.claude/commands/swarm/swarm-analysis.md

@@ -0,0 +1,8 @@
+# swarm-analysis
+
+Command documentation for swarm-analysis in category swarm.
+
+Usage:
+```bash
+npx claude-flow swarm swarm-analysis [options]
+```

.claude/commands/swarm/swarm-spawn.md

@@ -0,0 +1,19 @@
+# swarm-spawn
+
+Spawn agents in the swarm.
+
+## Usage
+```bash
+npx claude-flow swarm spawn [options]
+```
+
+## Options
+- `--type <type>` - Agent type
+- `--count <n>` - Number to spawn
+- `--capabilities <list>` - Agent capabilities
+
+## Examples
+```bash
+npx claude-flow swarm spawn --type coder --count 3
+npx claude-flow swarm spawn --type researcher --capabilities "web-search,analysis"
+```

.claude/commands/swarm/swarm-strategies.md

@@ -0,0 +1,8 @@
+# swarm-strategies
+
+Command documentation for swarm-strategies in category swarm.
+
+Usage:
+```bash
+npx claude-flow swarm swarm-strategies [options]
+```