agentic-flow 1.8.15 → 1.9.0

package/.claude/agents/templates/coordinator-swarm-init.md

@@ -14,18 +14,21 @@ hooks:
   pre: |
     echo "🚀 Swarm Initializer starting..."
     echo "📡 Preparing distributed coordination systems"
+    # Write initial status to memory
+    npx claude-flow@alpha memory store "swarm/init/status" "{\"status\":\"initializing\",\"timestamp\":$(date +%s)}" --namespace coordination
     # Check for existing swarms
-    memory_search "swarm_status" | tail -1 || echo "No existing swarms found"
+    npx claude-flow@alpha memory search "swarm/*" --namespace coordination || echo "No existing swarms found"
   post: |
     echo "✅ Swarm initialization complete"
-    memory_store "swarm_init_$(date +%s)" "Swarm successfully initialized with optimal topology"
+    # Write completion status with topology details
+    npx claude-flow@alpha memory store "swarm/init/complete" "{\"status\":\"ready\",\"topology\":\"$TOPOLOGY\",\"agents\":$AGENT_COUNT}" --namespace coordination
     echo "🌐 Inter-agent communication channels established"
 ---
 
 # Swarm Initializer Agent
 
 ## Purpose
-This agent specializes in initializing and configuring agent swarms for optimal performance. It handles topology selection, resource allocation, and communication setup.
+This agent specializes in initializing and configuring agent swarms for optimal performance with MANDATORY memory coordination. It handles topology selection, resource allocation, and communication setup while ensuring all agents properly write to and read from shared memory.
 
 ## Core Functionality
 
@@ -39,11 +42,23 @@ This agent specializes in initializing and configuring agent swarms for optimal
 - Allocates compute resources based on task complexity
 - Sets agent limits to prevent resource exhaustion
 - Configures memory namespaces for inter-agent communication
+- **ENFORCES memory write requirements for all agents**
 
 ### 3. Communication Setup
 - Establishes message passing protocols
-- Sets up shared memory channels
+- Sets up shared memory channels in "coordination" namespace
 - Configures event-driven coordination
+- **VERIFIES all agents are writing status updates to memory**
+
+### 4. MANDATORY Memory Coordination Protocol
+**EVERY agent spawned MUST:**
+1. **WRITE initial status** when starting: `swarm/[agent-name]/status`
+2. **UPDATE progress** after each step: `swarm/[agent-name]/progress`
+3. **SHARE artifacts** others need: `swarm/shared/[component]`
+4. **CHECK dependencies** before using: retrieve then wait if missing
+5. **SIGNAL completion** when done: `swarm/[agent-name]/complete`
+
+**ALL memory operations use namespace: "coordination"**
 
 ## Usage Examples
 

package/.claude/commands/coordination/README.md

@@ -0,0 +1,9 @@
+# Coordination Commands
+
+Commands for coordination operations in Claude Flow.
+
+## Available Commands
+
+- [swarm-init](./swarm-init.md)
+- [agent-spawn](./agent-spawn.md)
+- [task-orchestrate](./task-orchestrate.md)

package/.claude/commands/coordination/agent-spawn.md

@@ -0,0 +1,25 @@
+# agent-spawn
+
+Spawn a new agent in the current swarm.
+
+## Usage
+```bash
+npx claude-flow agent spawn [options]
+```
+
+## Options
+- `--type <type>` - Agent type (coder, researcher, analyst, tester, coordinator)
+- `--name <name>` - Custom agent name
+- `--skills <list>` - Specific skills (comma-separated)
+
+## Examples
+```bash
+# Spawn coder agent
+npx claude-flow agent spawn --type coder
+
+# With custom name
+npx claude-flow agent spawn --type researcher --name "API Expert"
+
+# With specific skills
+npx claude-flow agent spawn --type coder --skills "python,fastapi,testing"
+```

package/.claude/commands/coordination/init.md

@@ -0,0 +1,44 @@
+# Initialize Coordination Framework
+
+## 🎯 Key Principle
+**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
+
+## MCP Tool Usage in Claude Code
+
+**Tool:** `mcp__claude-flow__swarm_init`
+
+## Parameters
+```json
+{"topology": "mesh", "maxAgents": 5, "strategy": "balanced"}
+```
+
+## Description
+Set up a coordination topology to guide Claude Code's approach to complex tasks
+
+## Details
+This tool creates a coordination framework that helps Claude Code:
+- Break down complex problems systematically
+- Approach tasks from multiple perspectives
+- Maintain consistency across large projects
+- Work more efficiently through structured coordination
+
+Remember: This does NOT create actual coding agents. It creates a coordination pattern for Claude Code to follow.
+
+## Example Usage
+
+**In Claude Code:**
+1. Use the tool: `mcp__claude-flow__swarm_init`
+2. With parameters: `{"topology": "mesh", "maxAgents": 5, "strategy": "balanced"}`
+3. Claude Code then executes the coordinated plan using its native tools
+
+## Important Reminders
+- ✅ This tool provides coordination and structure
+- ✅ Claude Code performs all actual implementation
+- ❌ The tool does NOT write code
+- ❌ The tool does NOT access files directly
+- ❌ The tool does NOT execute commands
+
+## See Also
+- Main documentation: /claude.md
+- Other commands in this category
+- Workflow examples in /workflows/

package/.claude/commands/coordination/orchestrate.md

@@ -0,0 +1,43 @@
+# Coordinate Task Execution
+
+## 🎯 Key Principle
+**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
+
+## MCP Tool Usage in Claude Code
+
+**Tool:** `mcp__claude-flow__task_orchestrate`
+
+## Parameters
+```json
+{"task": "Implement authentication system", "strategy": "parallel", "priority": "high"}
+```
+
+## Description
+Break down and coordinate complex tasks for systematic execution by Claude Code
+
+## Details
+Orchestration strategies:
+- **parallel**: Claude Code works on independent components simultaneously
+- **sequential**: Step-by-step execution for dependent tasks
+- **adaptive**: Dynamically adjusts based on task complexity
+
+The orchestrator creates a plan that Claude Code follows using its native tools.
+
+## Example Usage
+
+**In Claude Code:**
+1. Use the tool: `mcp__claude-flow__task_orchestrate`
+2. With parameters: `{"task": "Implement authentication system", "strategy": "parallel", "priority": "high"}`
+3. Claude Code then executes the coordinated plan using its native tools
+
+## Important Reminders
+- ✅ This tool provides coordination and structure
+- ✅ Claude Code performs all actual implementation
+- ❌ The tool does NOT write code
+- ❌ The tool does NOT access files directly
+- ❌ The tool does NOT execute commands
+
+## See Also
+- Main documentation: /claude.md
+- Other commands in this category
+- Workflow examples in /workflows/

package/.claude/commands/coordination/spawn.md

@@ -0,0 +1,45 @@
+# Create Cognitive Patterns
+
+## 🎯 Key Principle
+**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
+
+## MCP Tool Usage in Claude Code
+
+**Tool:** `mcp__claude-flow__agent_spawn`
+
+## Parameters
+```json
+{"type": "researcher", "name": "Literature Analysis", "capabilities": ["deep-analysis"]}
+```
+
+## Description
+Define cognitive patterns that represent different approaches Claude Code can take
+
+## Details
+Agent types represent thinking patterns, not actual coders:
+- **researcher**: Systematic exploration approach
+- **coder**: Implementation-focused thinking
+- **analyst**: Data-driven decision making
+- **architect**: Big-picture system design
+- **reviewer**: Quality and consistency checking
+
+These patterns guide how Claude Code approaches different aspects of your task.
+
+## Example Usage
+
+**In Claude Code:**
+1. Use the tool: `mcp__claude-flow__agent_spawn`
+2. With parameters: `{"type": "researcher", "name": "Literature Analysis", "capabilities": ["deep-analysis"]}`
+3. Claude Code then executes the coordinated plan using its native tools
+
+## Important Reminders
+- ✅ This tool provides coordination and structure
+- ✅ Claude Code performs all actual implementation
+- ❌ The tool does NOT write code
+- ❌ The tool does NOT access files directly
+- ❌ The tool does NOT execute commands
+
+## See Also
+- Main documentation: /claude.md
+- Other commands in this category
+- Workflow examples in /workflows/

package/.claude/commands/coordination/swarm-init.md

@@ -0,0 +1,85 @@
+# swarm init
+
+Initialize a Claude Flow swarm with specified topology and configuration.
+
+## Usage
+
+```bash
+npx claude-flow swarm init [options]
+```
+
+## Options
+
+- `--topology, -t <type>` - Swarm topology: mesh, hierarchical, ring, star (default: hierarchical)
+- `--max-agents, -m <number>` - Maximum number of agents (default: 8)
+- `--strategy, -s <type>` - Execution strategy: balanced, parallel, sequential (default: parallel)
+- `--auto-spawn` - Automatically spawn agents based on task complexity
+- `--memory` - Enable cross-session memory persistence
+- `--github` - Enable GitHub integration features
+
+## Examples
+
+### Basic initialization
+
+```bash
+npx claude-flow swarm init
+```
+
+### Mesh topology for research
+
+```bash
+npx claude-flow swarm init --topology mesh --max-agents 5 --strategy balanced
+```
+
+### Hierarchical for development
+
+```bash
+npx claude-flow swarm init --topology hierarchical --max-agents 10 --strategy parallel --auto-spawn
+```
+
+### GitHub-focused swarm
+
+```bash
+npx claude-flow swarm init --topology star --github --memory
+```
+
+## Topologies
+
+### Mesh
+
+- All agents connect to all others
+- Best for: Research, exploration, brainstorming
+- Communication: High overhead, maximum information sharing
+
+### Hierarchical
+
+- Tree structure with clear command chain
+- Best for: Development, structured tasks, large projects
+- Communication: Efficient, clear responsibilities
+
+### Ring
+
+- Agents connect in a circle
+- Best for: Pipeline processing, sequential workflows
+- Communication: Low overhead, ordered processing
+
+### Star
+
+- Central coordinator with satellite agents
+- Best for: Simple tasks, centralized control
+- Communication: Minimal overhead, clear coordination
+
+## Integration with Claude Code
+
+Once initialized, use MCP tools in Claude Code:
+
+```javascript
+mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 8 }
+```
+
+## See Also
+
+- `agent spawn` - Create swarm agents
+- `task orchestrate` - Coordinate task execution
+- `swarm status` - Check swarm state
+- `swarm monitor` - Real-time monitoring

package/.claude/commands/coordination/task-orchestrate.md

@@ -0,0 +1,25 @@
+# task-orchestrate
+
+Orchestrate complex tasks across the swarm.
+
+## Usage
+```bash
+npx claude-flow task orchestrate [options]
+```
+
+## Options
+- `--task <description>` - Task description
+- `--strategy <type>` - Orchestration strategy
+- `--priority <level>` - Task priority (low, medium, high, critical)
+
+## Examples
+```bash
+# Orchestrate development task
+npx claude-flow task orchestrate --task "Implement user authentication"
+
+# High priority task
+npx claude-flow task orchestrate --task "Fix production bug" --priority critical
+
+# With specific strategy
+npx claude-flow task orchestrate --task "Refactor codebase" --strategy parallel
+```

package/.claude/commands/hooks/overview.md

@@ -1,26 +1,31 @@
 # Claude Code Hooks for claude-flow
 
 ## Purpose
-Automatically coordinate, format, and learn from Claude Code operations using hooks.
+Automatically coordinate, format, and learn from Claude Code operations using hooks with MCP tool integration.
 
 ## Available Hooks
 
 ### Pre-Operation Hooks
 - **pre-edit**: Validate and assign agents before file modifications
-- **pre-bash**: Check command safety and resource requirements
+- **pre-bash**: Check command safety and resource requirements  
 - **pre-task**: Auto-spawn agents for complex tasks
 
 ### Post-Operation Hooks
-- **post-edit**: Auto-format code and train neural patterns
+- **post-edit**: Auto-format code, train neural patterns, update memory
 - **post-bash**: Log execution and update metrics
 - **post-search**: Cache results and improve search patterns
 
 ### MCP Integration Hooks
 - **mcp-initialized**: Persist swarm configuration
-- **agent-spawned**: Update agent roster
-- **task-orchestrated**: Monitor task progress
+- **agent-spawned**: Update agent roster and memory
+- **task-orchestrated**: Monitor task progress through memory
 - **neural-trained**: Save pattern improvements
 
+### Memory Coordination Hooks
+- **memory-write**: Triggered when agents write to coordination memory
+- **memory-read**: Triggered when agents read from coordination memory
+- **memory-sync**: Synchronize memory across swarm agents
+
 ### Session Hooks
 - **notify**: Custom notifications with swarm status
 - **session-end**: Generate summary and save state
@@ -37,7 +42,16 @@ Hooks are configured in `.claude/settings.json`:
         "matcher": "^(Write|Edit|MultiEdit)$",
         "hooks": [{
           "type": "command",
-          "command": "npx claude-flow hook pre-edit --file '${tool.params.file_path}'"
+          "command": "npx claude-flow hook pre-edit --file '${tool.params.file_path}' --memory-key 'swarm/editor/current'"
+        }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(Write|Edit|MultiEdit)$",
+        "hooks": [{
+          "type": "command",
+          "command": "npx claude-flow hook post-edit --file '${tool.params.file_path}' --memory-key 'swarm/editor/complete'"
         }]
       }
     ]
@@ -45,14 +59,74 @@ Hooks are configured in `.claude/settings.json`:
 }
 ```
 
+## MCP Tool Integration in Hooks
+
+Hooks automatically trigger MCP tools for coordination:
+
+```javascript
+// Pre-task hook spawns agents
+npx claude-flow hook pre-task --description "[task]"
+// Internally calls:
+mcp__claude-flow__agent_spawn { type: "appropriate-agent" }
+
+// Post-edit hook updates memory
+npx claude-flow hook post-edit --file "[file]"
+// Internally calls:
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/editor/[file]",
+  namespace: "coordination",
+  value: JSON.stringify({ file, changes, timestamp })
+}
+
+// Session-end hook persists state
+npx claude-flow hook session-end
+// Internally calls:
+mcp__claude-flow__memory_persist { sessionId: "[session-id]" }
+```
+
+## Memory Coordination Protocol
+
+All hooks follow the mandatory memory write pattern:
+
+```javascript
+// 1. STATUS - Hook starts
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/hooks/[hook-name]/status",
+  namespace: "coordination",
+  value: JSON.stringify({ status: "running", hook: "[name]" })
+}
+
+// 2. PROGRESS - Hook processes
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/hooks/[hook-name]/progress",
+  namespace: "coordination",
+  value: JSON.stringify({ progress: 50, action: "processing" })
+}
+
+// 3. COMPLETE - Hook finishes
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/hooks/[hook-name]/complete",
+  namespace: "coordination",
+  value: JSON.stringify({ status: "complete", result: "success" })
+}
+```
+
 ## Benefits
 - 🤖 Automatic agent assignment based on file type
 - 🎨 Consistent code formatting
-- 🧠 Continuous neural pattern improvement
-- 💾 Cross-session memory persistence
-- 📊 Performance metrics tracking
+- 🧠 Continuous neural pattern improvement  
+- 💾 Cross-session memory persistence via MCP tools
+- 📊 Performance metrics tracking through memory
+- 🔄 Automatic memory coordination between agents
+- 🎯 Smart agent spawning based on task analysis
 
 ## See Also
 - [Pre-Edit Hook](./pre-edit.md)
 - [Post-Edit Hook](./post-edit.md)
-- [Session End Hook](./session-end.md)
+- [Session End Hook](./session-end.md)
+- [Memory Usage](../memory/memory-usage.md)
+- [Agent Spawning](../agents/agent-spawning.md)

package/.claude/commands/memory/README.md

@@ -0,0 +1,9 @@
+# Memory Commands
+
+Commands for memory operations in Claude Flow.
+
+## Available Commands
+
+- [memory-usage](./memory-usage.md)
+- [memory-persist](./memory-persist.md)
+- [memory-search](./memory-search.md)

package/.claude/commands/memory/memory-persist.md

@@ -0,0 +1,25 @@
+# memory-persist
+
+Persist memory across sessions.
+
+## Usage
+```bash
+npx claude-flow memory persist [options]
+```
+
+## Options
+- `--export <file>` - Export to file
+- `--import <file>` - Import from file
+- `--compress` - Compress memory data
+
+## Examples
+```bash
+# Export memory
+npx claude-flow memory persist --export memory-backup.json
+
+# Import memory
+npx claude-flow memory persist --import memory-backup.json
+
+# Compressed export
+npx claude-flow memory persist --export memory.gz --compress
+```

package/.claude/commands/memory/memory-search.md

@@ -0,0 +1,25 @@
+# memory-search
+
+Search through stored memory.
+
+## Usage
+```bash
+npx claude-flow memory search [options]
+```
+
+## Options
+- `--query <text>` - Search query
+- `--pattern <regex>` - Pattern matching
+- `--limit <n>` - Result limit
+
+## Examples
+```bash
+# Search memory
+npx claude-flow memory search --query "authentication"
+
+# Pattern search
+npx claude-flow memory search --pattern "api-.*"
+
+# Limited results
+npx claude-flow memory search --query "config" --limit 10
+```

package/.claude/commands/memory/memory-usage.md

@@ -0,0 +1,25 @@
+# memory-usage
+
+Manage persistent memory storage.
+
+## Usage
+```bash
+npx claude-flow memory usage [options]
+```
+
+## Options
+- `--action <type>` - Action (store, retrieve, list, clear)
+- `--key <key>` - Memory key
+- `--value <data>` - Data to store (JSON)
+
+## Examples
+```bash
+# Store memory
+npx claude-flow memory usage --action store --key "project-config" --value '{"api": "v2"}'
+
+# Retrieve memory
+npx claude-flow memory usage --action retrieve --key "project-config"
+
+# List all keys
+npx claude-flow memory usage --action list
+```

package/.claude/commands/memory/neural.md

@@ -0,0 +1,47 @@
+# Neural Pattern Training
+
+## 🎯 Key Principle
+**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
+
+## MCP Tool Usage in Claude Code
+
+**Tool:** `mcp__claude-flow__neural_train`
+
+## Parameters
+```json
+{
+  "pattern_type": "coordination",
+  "training_data": "task decomposition patterns",
+  "epochs": 50
+}
+```
+
+## Description
+Improve coordination patterns through neural network training
+
+## Details
+Training improves:
+- Task breakdown effectiveness
+- Coordination pattern selection
+- Resource allocation strategies
+- Overall coordination efficiency
+
+## Example Usage
+
+**In Claude Code:**
+1. Train coordination patterns: Use tool `mcp__claude-flow__neural_train` with parameters `{"pattern_type": "coordination", "training_data": "successful task patterns", "epochs": 50}`
+2. Train optimization patterns: Use tool `mcp__claude-flow__neural_train` with parameters `{"pattern_type": "optimization", "training_data": "performance metrics", "epochs": 30}`
+3. Check training status: Use tool `mcp__claude-flow__neural_status`
+4. Analyze patterns: Use tool `mcp__claude-flow__neural_patterns` with parameters `{"action": "analyze"}`
+
+## Important Reminders
+- ✅ This tool provides coordination and structure
+- ✅ Claude Code performs all actual implementation
+- ❌ The tool does NOT write code
+- ❌ The tool does NOT access files directly
+- ❌ The tool does NOT execute commands
+
+## See Also
+- Main documentation: /CLAUDE.md
+- Other commands in this category
+- Workflow examples in /workflows/

package/.claude/commands/memory/usage.md

@@ -0,0 +1,46 @@
+# Memory Management
+
+## 🎯 Key Principle
+**This tool coordinates Claude Code's actions. It does NOT write code or create content.**
+
+## MCP Tool Usage in Claude Code
+
+**Tool:** `mcp__claude-flow__memory_usage`
+
+## Parameters
+```json
+{
+  "action": "retrieve",
+  "namespace": "default"
+}
+```
+
+## Description
+Track persistent memory usage across Claude Code sessions
+
+## Details
+Memory helps Claude Code:
+- Maintain context between sessions
+- Remember project decisions
+- Track implementation patterns
+- Store coordination strategies that worked well
+
+## Example Usage
+
+**In Claude Code:**
+1. Store memory: Use tool `mcp__claude-flow__memory_usage` with parameters `{"action": "store", "key": "project_context", "value": "authentication system design"}`
+2. Retrieve memory: Use tool `mcp__claude-flow__memory_usage` with parameters `{"action": "retrieve", "key": "project_context"}`
+3. List memories: Use tool `mcp__claude-flow__memory_usage` with parameters `{"action": "list", "namespace": "default"}`
+4. Search memories: Use tool `mcp__claude-flow__memory_search` with parameters `{"pattern": "auth*"}`
+
+## Important Reminders
+- ✅ This tool provides coordination and structure
+- ✅ Claude Code performs all actual implementation
+- ❌ The tool does NOT write code
+- ❌ The tool does NOT access files directly
+- ❌ The tool does NOT execute commands
+
+## See Also
+- Main documentation: /CLAUDE.md
+- Other commands in this category
+- Workflow examples in /workflows/