@aigentic/claude-flow 3.7.0-alpha.69

package/.claude-plugin/docs/QUICKSTART.md

@@ -0,0 +1,361 @@
+# 🚀 Claude Flow Plugin - Quickstart Guide
+
+Get started with Claude Flow in 5 minutes!
+
+---
+
+## 📦 Installation
+
+### Quick Install (Recommended)
+
+In Claude Code:
+
+```
+/plugin add ruvnet/claude-flow
+/restart
+```
+
+### Local Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/ruvnet/claude-flow.git
+cd claude-flow
+```
+
+Then in Claude Code:
+```
+/plugin add .
+/restart
+```
+
+---
+
+## ✅ Verify Installation
+
+In Claude Code:
+
+```
+/plugin list
+```
+
+Look for `claude-flow` in the active plugins.
+
+Try a command:
+```
+/coordination-swarm-init
+```
+
+Or type `/` to see all 150+ commands.
+
+---
+
+## 🎯 Your First Swarm
+
+### 1. Initialize a Swarm
+
+In Claude Code, run:
+
+```
+/coordination-swarm-init
+```
+
+This creates a hierarchical swarm with:
+- Automatic agent spawning
+- Cross-session memory
+- Performance optimization
+
+### 2. Spawn Specialized Agents
+
+```
+/coordination-agent-spawn
+```
+
+Choose from 74+ agents:
+- `coder` - Code implementation
+- `tester` - Test creation
+- `reviewer` - Code review
+- `planner` - Project planning
+- And 70 more!
+
+### 3. Orchestrate a Task
+
+```
+/coordination-task-orchestrate "Build a REST API with authentication"
+```
+
+The swarm automatically:
+1. Analyzes requirements
+2. Spawns appropriate agents
+3. Coordinates parallel execution
+4. Monitors progress
+5. Reports results
+
+---
+
+## 💻 Common Workflows
+
+### Full-Stack Development
+
+```bash
+# Initialize development swarm
+/swarm-development
+
+# Spawns: backend-dev, coder, tester, reviewer
+# Orchestrates: design → implement → test → review
+```
+
+### SPARC TDD Workflow
+
+```bash
+# Specification phase
+/sparc-modes specification "Shopping cart system"
+
+# Architecture design
+/sparc-architect
+
+# TDD implementation
+/sparc-tdd
+
+# Review and optimize
+/sparc-reviewer
+/sparc-optimizer
+```
+
+### GitHub Automation
+
+```bash
+# Analyze repository
+/github-repo-analyze
+
+# Multi-agent PR review
+/github-code-review-swarm
+
+# Automated PR management
+/github-pr-manager
+
+# Release coordination
+/github-release-manager
+```
+
+---
+
+## 🧪 Try These Commands
+
+### Monitoring
+
+```bash
+/monitoring-status          # System overview
+/monitoring-swarm-monitor   # Real-time swarm view
+/monitoring-agent-metrics   # Performance metrics
+```
+
+### Analysis
+
+```bash
+/analysis-performance-report     # Performance analysis
+/analysis-bottleneck-detect      # Find bottlenecks
+/analysis-token-usage            # Token consumption
+```
+
+### Optimization
+
+```bash
+/optimization-auto-topology      # Auto-select topology
+/optimization-parallel-execution # Parallel task execution
+/optimization-cache-manage       # Cache management
+```
+
+---
+
+## 🎨 Agent Showcase
+
+### Core Development Agents
+
+```
+/coordination-agent-spawn coder
+/coordination-agent-spawn tester
+/coordination-agent-spawn reviewer
+```
+
+### GitHub Automation Agents
+
+```
+/coordination-agent-spawn pr-manager
+/coordination-agent-spawn code-review-swarm
+/coordination-agent-spawn release-manager
+```
+
+### Swarm Coordination Agents
+
+```
+/coordination-agent-spawn hierarchical-coordinator
+/coordination-agent-spawn mesh-coordinator
+/coordination-agent-spawn adaptive-coordinator
+```
+
+---
+
+## 🔧 MCP Configuration
+
+### Add MCP Servers
+
+```bash
+# Core MCP (required)
+claude mcp add claude-flow npx claude-flow@alpha mcp start
+
+# Enhanced coordination (optional)
+claude mcp add ruv-swarm npx ruv-swarm mcp start
+
+# Cloud features (optional - requires auth)
+claude mcp add flow-nexus npx flow-nexus@latest mcp start
+```
+
+### Test MCP Integration
+
+In Claude Code:
+
+```
+List available MCP tools for claude-flow
+```
+
+Expected: 40+ tools including:
+- `swarm_init`
+- `agent_spawn`
+- `task_orchestrate`
+- `memory_usage`
+- `neural_train`
+- And more!
+
+---
+
+## 📚 Example: Build a Todo App
+
+### Step 1: Initialize
+
+```
+/coordination-swarm-init
+```
+
+### Step 2: Specify Requirements
+
+```
+/sparc-modes specification "Todo app with React frontend and Express backend"
+```
+
+### Step 3: Design Architecture
+
+```
+/sparc-architect
+```
+
+### Step 4: TDD Implementation
+
+```
+/sparc-tdd
+```
+
+### Step 5: Monitor Progress
+
+```
+/monitoring-swarm-monitor
+```
+
+### Step 6: Review & Optimize
+
+```
+/sparc-reviewer
+/sparc-optimizer
+```
+
+### Step 7: Performance Report
+
+```
+/analysis-performance-report
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Commands Not Found
+
+```bash
+# Verify installation
+bash scripts/verify.sh
+
+# Check commands directory
+ls ~/.claude/commands/
+
+# Restart Claude Code
+```
+
+### MCP Not Working
+
+```bash
+# Check settings
+cat ~/.claude/settings.json
+
+# Verify MCP package
+npx claude-flow@alpha --version
+
+# Reinstall if needed
+npm install -g claude-flow@alpha
+```
+
+### Agents Not Spawning
+
+```bash
+# Check agents directory
+ls ~/.claude/agents/
+
+# Verify permissions
+chmod -R 755 ~/.claude/agents/
+
+# Restart Claude Code
+```
+
+---
+
+## 🎓 Next Steps
+
+1. **Explore Commands**: Browse `~/.claude/commands/` for all 150+ commands
+2. **Try Agents**: Experiment with different specialized agents
+3. **Read User Guide**: `docs/USER_GUIDE.md` for detailed documentation
+4. **Check Examples**: `docs/EXAMPLES.md` for real-world usage
+5. **Join Community**: GitHub Discussions for help and sharing
+
+---
+
+## 📖 Quick Reference
+
+### Most Used Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/coordination-swarm-init` | Initialize swarm |
+| `/coordination-agent-spawn` | Spawn agents |
+| `/coordination-task-orchestrate` | Orchestrate tasks |
+| `/sparc-tdd` | TDD workflow |
+| `/github-pr-manager` | PR management |
+| `/monitoring-status` | System status |
+| `/analysis-performance-report` | Performance |
+
+### Most Used Agents
+
+| Agent | Purpose |
+|-------|---------|
+| `coder` | Code implementation |
+| `tester` | Test creation |
+| `reviewer` | Code review |
+| `planner` | Project planning |
+| `backend-dev` | Backend development |
+| `pr-manager` | PR automation |
+
+---
+
+## 🚀 You're Ready!
+
+Start building with Claude Flow's enterprise AI agent orchestration.
+
+**Happy coding!** 🎉

package/.claude-plugin/docs/STRUCTURE.md

@@ -0,0 +1,128 @@
+# Claude Flow Plugin Structure
+
+## Official Claude Code Plugin Format
+
+This plugin follows the official Claude Code plugin specification.
+
+## Directory Structure
+
+```
+claude-flow/
+├── .claude-plugin/              # Plugin metadata and documentation
+│   ├── plugin.json              # Plugin manifest
+│   ├── marketplace.json         # Marketplace distribution metadata
+│   ├── README.md                # Complete documentation (20KB)
+│   ├── STRUCTURE.md             # This file
+│   ├── docs/
+│   │   └── QUICKSTART.md        # 5-minute quickstart
+│   └── scripts/
+│       ├── install.sh           # Installation script
+│       ├── verify.sh            # Verification script
+│       └── uninstall.sh         # Uninstallation script
+│
+├── commands/                     # 150+ slash commands
+│   ├── coordination/            # Swarm coordination (6 commands)
+│   ├── sparc/                   # SPARC methodology (18 commands)
+│   ├── github/                  # GitHub integration (18 commands)
+│   ├── hive-mind/               # Hive mind (11 commands)
+│   ├── hooks/                   # Hooks configuration (5 commands)
+│   ├── memory/                  # Memory management (5 commands)
+│   ├── monitoring/              # Monitoring (5 commands)
+│   ├── optimization/            # Optimization (5 commands)
+│   ├── analysis/                # Analysis (5 commands)
+│   ├── automation/              # Automation (6 commands)
+│   ├── swarm/                   # Swarm management (15 commands)
+│   ├── workflows/               # Workflows (5 commands)
+│   ├── training/                # Neural training (5 commands)
+│   └── flow-nexus/              # Flow Nexus integration (9 commands)
+│
+├── agents/                      # 74+ specialized agents
+│   ├── core/                    # Core development (5 agents)
+│   ├── swarm/                   # Swarm coordination (5 agents)
+│   ├── consensus/               # Consensus protocols (7 agents)
+│   ├── github/                  # GitHub automation (13 agents)
+│   ├── specialized/             # Specialized development (8 agents)
+│   ├── sparc/                   # SPARC methodology (4 agents)
+│   ├── hive-mind/               # Hive mind (5 agents)
+│   └── optimization/            # Performance optimization (5 agents)
+│
+└── hooks/                       # Event handlers
+    └── hooks.json               # Hook configuration
+
+```
+
+## Installation
+
+Users install with:
+
+```
+/plugin add ruvnet/claude-flow
+/restart
+```
+
+## Components
+
+### Plugin Metadata
+- **plugin.json**: Plugin manifest with configuration
+  - Plugin name, version, description
+  - Author and repository information
+  - MCP server configuration
+  - Engine requirements
+- **marketplace.json**: Marketplace distribution metadata
+  - Marketplace owner information
+  - Plugin listing and features
+  - Requirements and dependencies
+
+### Commands (`commands/`)
+- Markdown files (.md)
+- Automatically discovered by Claude Code
+- 150+ commands across 19 categories
+- Named with kebab-case (e.g., `coordination-swarm-init.md`)
+
+### Agents (`agents/`)
+- Markdown files with YAML frontmatter
+- Available for delegation
+- 74+ specialized agents across 20 categories
+- Named with kebab-case (e.g., `backend-dev.md`)
+
+### Hooks (`hooks/hooks.json`)
+- Event handler configuration
+- Integration with Claude Flow coordination
+- Pre/post task execution, session management
+
+## MCP Integration
+
+The plugin configures 3 MCP servers:
+
+1. **claude-flow** (Required)
+   - 40+ orchestration tools
+   - Swarm coordination
+   - Agent management
+
+2. **ruv-swarm** (Optional)
+   - Enhanced coordination
+   - WASM acceleration
+
+3. **flow-nexus** (Optional)
+   - 70+ cloud tools
+   - Requires authentication
+
+## Documentation
+
+- **README.md**: Complete plugin documentation (20KB)
+- **marketplace.json**: Marketplace distribution metadata
+- **docs/INSTALLATION.md**: Installation instructions
+- **docs/PLUGIN_SUMMARY.md**: Production status
+- **docs/STRUCTURE.md**: This file
+- **docs/QUICKSTART.md**: 5-minute quickstart
+
+## Version
+
+- **Version**: 2.5.0
+- **License**: MIT
+- **Author**: rUv
+- **Compatibility**: Claude Code >= 2.0.0
+
+## Status
+
+✅ **PRODUCTION READY**

package/.claude-plugin/hooks/hooks.json

@@ -0,0 +1,75 @@
+{
+  "_note": "#1921 — hook commands invoke scripts/ruflo-hook.sh (resilient shim): prefers a locally-installed `ruflo`/`claude-flow` binary, falls back to `npx --prefer-offline`, and always exits 0 so a CLI/install failure (e.g. arborist `Invalid Version` on npm 10.8.x) never surfaces an error in Claude Code or blocks a turn. The trailing `|| true` guards the case where $CLAUDE_PLUGIN_ROOT is unset (older Claude Code) — the hook then no-ops silently. DO NOT revert to a bare `npx <pkg>@alpha hooks …` per fire.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/ruflo-hook.sh\" modify-bash || true"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/ruflo-hook.sh\" modify-file || true"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cat | jq -r '.tool_input.command // empty' | tr '\\n' '\\0' | xargs -0 -I {} \"${CLAUDE_PLUGIN_ROOT}/scripts/ruflo-hook.sh\" post-command --command '{}' --track-metrics true --store-results true || true"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cat | jq -r '.tool_input.file_path // .tool_input.path // empty' | tr '\\n' '\\0' | xargs -0 -I {} \"${CLAUDE_PLUGIN_ROOT}/scripts/ruflo-hook.sh\" post-edit --file '{}' --format true --update-memory true || true"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "manual",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/bin/bash -c 'INPUT=$(cat); CUSTOM=$(echo \"$INPUT\" | jq -r \".custom_instructions // \\\"\\\"\"); echo \"🔄 PreCompact Guidance:\"; echo \"📋 IMPORTANT: Review CLAUDE.md in project root for:\"; echo \"   • 54 available agents and concurrent usage patterns\"; echo \"   • Swarm coordination strategies (hierarchical, mesh, adaptive)\"; echo \"   • SPARC methodology workflows with batchtools optimization\"; echo \"   • Critical concurrent execution rules (GOLDEN RULE: 1 MESSAGE = ALL OPERATIONS)\"; if [ -n \"$CUSTOM\" ]; then echo \"🎯 Custom compact instructions: $CUSTOM\"; fi; echo \"✅ Ready for compact operation\"'"
+          }
+        ]
+      },
+      {
+        "matcher": "auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/bin/bash -c 'echo \"🔄 Auto-Compact Guidance (Context Window Full):\"; echo \"📋 CRITICAL: Before compacting, ensure you understand:\"; echo \"   • All 54 agents available in .claude/agents/ directory\"; echo \"   • Concurrent execution patterns from CLAUDE.md\"; echo \"   • Batchtools optimization for 300% performance gains\"; echo \"   • Swarm coordination strategies for complex tasks\"; echo \"⚡ Apply GOLDEN RULE: Always batch operations in single messages\"; echo \"✅ Auto-compact proceeding with full agent context\"'"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/ruflo-hook.sh\" session-end --generate-summary true --persist-state true --export-metrics true || true"
+          }
+        ]
+      }
+    ]
+  }
+}