monomind 1.8.0 → 1.9.0

package/.claude/commands/swarm/optimization.md

@@ -1,117 +1,84 @@
+---
+name: swarm-optimization
+description: Optimization swarm strategy — performance profiling, bottleneck detection, and coordinated optimization through specialized mesh agents
+---
+
 # Optimization Swarm Strategy
 
-## Purpose
-Performance optimization through specialized analysis.
+Performance optimization through specialized analysis agents.
+
+## How to Invoke
+
+```
+Skill("swarm:optimization")
+```
+
+Then describe the optimization target:
+> "Start an optimization swarm to improve API response times."
+> "Run an optimization swarm on the memory usage in the agent system."
 
-## Activation
+---
+
+## Swarm Setup
 
-### Using MCP Tools
 ```javascript
 // Initialize optimization swarm
 mcp__monomind__swarm_init({
-  "topology": "mesh",
-  "maxAgents": 6,
-  "strategy": "adaptive"
+  topology: "mesh",
+  maxAgents: 6,
+  strategy: "adaptive"
 })
 
-// Orchestrate optimization task
-mcp__monomind__task_orchestrate({
-  "task": "optimize performance",
-  "strategy": "parallel",
-  "priority": "high"
+// Coordinate optimization
+mcp__monomind__coordination_orchestrate({
+  task: "optimize performance",
+  strategy: "parallel"
 })
 ```
 
-### Using CLI (Fallback)
-`npx monomind swarm "optimize performance" --strategy optimization`
+```bash
+# CLI equivalent
+npx monomind swarm init --topology mesh --max-agents 6
+npx monomind swarm start "optimize performance" --strategy optimization --parallel
+```
 
 ## Agent Roles
 
-### Agent Spawning with MCP
 ```javascript
-// Spawn optimization agents
-mcp__monomind__agent_spawn({
-  "type": "optimizer",
-  "name": "Performance Profiler",
-  "capabilities": ["profiling", "bottleneck-detection"]
-})
-
-mcp__monomind__agent_spawn({
-  "type": "analyst",
-  "name": "Memory Analyzer",
-  "capabilities": ["memory-analysis", "leak-detection"]
-})
-
-mcp__monomind__agent_spawn({
-  "type": "optimizer",
-  "name": "Code Optimizer",
-  "capabilities": ["code-optimization", "refactoring"]
-})
-
-mcp__monomind__agent_spawn({
-  "type": "tester",
-  "name": "Benchmark Runner",
-  "capabilities": ["benchmarking", "performance-testing"]
-})
+mcp__monomind__agent_spawn({ type: "optimizer", capabilities: ["profiling", "bottleneck-detection"] })
+mcp__monomind__agent_spawn({ type: "analyst", capabilities: ["memory-analysis", "leak-detection"] })
+mcp__monomind__agent_spawn({ type: "optimizer", capabilities: ["code-optimization", "refactoring"] })
+mcp__monomind__agent_spawn({ type: "tester", capabilities: ["benchmarking", "performance-testing"] })
 ```
 
-## Optimization Areas
+## Performance Analysis
 
-### Performance Analysis
 ```javascript
-// Analyze bottlenecks
-mcp__monomind__bottleneck_analyze({
-  "component": "all",
-  "metrics": ["cpu", "memory", "io", "network"]
-})
+// Profile performance
+mcp__monomind__performance_profile({ target: "api", metrics: ["cpu", "memory", "latency"] })
 
-// Run benchmarks
-mcp__monomind__benchmark_run({
-  "suite": "performance"
-})
-
-// WASM optimization
-mcp__monomind__wasm_optimize({
-  "operation": "simd-acceleration"
-})
-```
+// Find bottlenecks
+mcp__monomind__performance_bottleneck({ component: "all" })
 
-### Optimization Operations
-```javascript
-// Optimize topology
-mcp__monomind__topology_optimize({
-  "swarmId": "optimization-swarm"
-})
-
-// DAA optimization
-mcp__monomind__daa_optimization({
-  "target": "performance",
-  "metrics": ["speed", "memory", "efficiency"]
-})
+// Performance report
+mcp__monomind__performance_report({ format: "detailed", timeframe: "7d" })
 
-// Load balancing
-mcp__monomind__load_balance({
-  "swarmId": "optimization-swarm",
-  "tasks": optimizationTasks
-})
+// Benchmark results
+mcp__monomind__performance_benchmark({ suite: "performance" })
 ```
 
-### Monitoring and Reporting
+## Load Balancing
+
 ```javascript
-// Performance report
-mcp__monomind__performance_report({
-  "format": "detailed",
-  "timeframe": "7d"
+// Balance work across optimization agents
+mcp__monomind__coordination_load_balance({
+  tasks: ["profile", "analyze", "optimize", "benchmark"]
 })
+```
 
-// Trend analysis
-mcp__monomind__trend_analysis({
-  "metric": "performance",
-  "period": "30d"
-})
+## Monitoring
 
-// Cost analysis
-mcp__monomind__cost_analysis({
-  "timeframe": "30d"
-})
+```javascript
+mcp__monomind__swarm_status({ swarmId: "current" })
+mcp__monomind__system_metrics({})
 ```

package/.claude/commands/swarm/research.md

@@ -1,136 +1,76 @@
+---
+name: swarm-research
+description: Research swarm strategy — parallel information gathering with mesh topology for deep research, literature review, and knowledge synthesis
+---
+
 # Research Swarm Strategy
 
-## Purpose
 Deep research through parallel information gathering.
 
-## Activation
+## How to Invoke
 
-### Using MCP Tools
-```javascript
-// Initialize research swarm
-mcp__monomind__swarm_init({
-  "topology": "mesh",
-  "maxAgents": 6,
-  "strategy": "adaptive"
-})
-
-// Orchestrate research task
-mcp__monomind__task_orchestrate({
-  "task": "research topic X",
-  "strategy": "parallel",
-  "priority": "medium"
-})
+```
+Skill("swarm:research")
 ```
 
-### Using CLI (Fallback)
-`npx monomind swarm "research topic X" --strategy research`
+Then describe the research topic:
+> "Start a research swarm on AI agent coordination patterns."
+> "Research best practices for distributed consensus algorithms."
 
-## Agent Roles
+---
 
-### Agent Spawning with MCP
-```javascript
-// Spawn research agents
-mcp__monomind__agent_spawn({
-  "type": "researcher",
-  "name": "Web Researcher",
-  "capabilities": ["web-search", "content-extraction", "source-validation"]
-})
+## Swarm Setup
 
-mcp__monomind__agent_spawn({
-  "type": "researcher",
-  "name": "Academic Researcher",
-  "capabilities": ["paper-analysis", "citation-tracking", "literature-review"]
+```javascript
+// Initialize research swarm
+mcp__monomind__swarm_init({
+  topology: "mesh",
+  maxAgents: 6,
+  strategy: "adaptive"
 })
 
-mcp__monomind__agent_spawn({
-  "type": "analyst",
-  "name": "Data Analyst",
-  "capabilities": ["data-processing", "statistical-analysis", "visualization"]
+// Coordinate research
+mcp__monomind__coordination_orchestrate({
+  task: "research topic X",
+  strategy: "parallel"
 })
+```
 
-mcp__monomind__agent_spawn({
-  "type": "documenter",
-  "name": "Report Writer",
-  "capabilities": ["synthesis", "technical-writing", "formatting"]
-})
+```bash
+# CLI equivalent
+npx monomind swarm init --topology mesh --max-agents 6
+npx monomind swarm start "research topic X" --strategy research --parallel
 ```
 
-## Research Methods
+## Agent Roles
 
-### Information Gathering
 ```javascript
-// Parallel information collection
-mcp__monomind__parallel_execute({
-  "tasks": [
-    { "id": "web-search", "command": "search recent publications" },
-    { "id": "academic-search", "command": "search academic databases" },
-    { "id": "data-collection", "command": "gather relevant datasets" }
-  ]
-})
-
-// Store research findings
-mcp__monomind__memory_usage({
-  "action": "store",
-  "key": "research-findings-" + Date.now(),
-  "value": JSON.stringify(findings),
-  "namespace": "research",
-  "ttl": 604800 // 7 days
-})
+mcp__monomind__agent_spawn({ type: "researcher", capabilities: ["web-search", "content-extraction", "source-validation"] })
+mcp__monomind__agent_spawn({ type: "researcher", capabilities: ["paper-analysis", "citation-tracking", "literature-review"] })
+mcp__monomind__agent_spawn({ type: "analyst", capabilities: ["data-processing", "statistical-analysis"] })
+mcp__monomind__agent_spawn({ type: "documenter", capabilities: ["synthesis", "technical-writing", "formatting"] })
 ```
 
-### Analysis and Validation
-```javascript
-// Pattern recognition in findings
-mcp__monomind__pattern_recognize({
-  "data": researchData,
-  "patterns": ["trend", "correlation", "outlier"]
-})
-
-// Cognitive analysis
-mcp__monomind__cognitive_analyze({
-  "behavior": "research-synthesis"
-})
-
-// Cross-reference validation
-mcp__monomind__quality_assess({
-  "target": "research-sources",
-  "criteria": ["credibility", "relevance", "recency"]
-})
-```
+## Knowledge Management
 
-### Knowledge Management
 ```javascript
-// Search existing knowledge
-mcp__monomind__memory_search({
-  "pattern": "topic X",
-  "namespace": "research",
-  "limit": 20
+// Store research findings for future sessions
+mcp__monomind__memory_store({
+  key: "research-findings",
+  value: "summary of findings",
+  namespace: "research"
 })
 
-// Create knowledge connections
-mcp__monomind__neural_patterns({
-  "action": "learn",
-  "operation": "knowledge-graph",
-  "metadata": {
-    "topic": "X",
-    "connections": relatedTopics
-  }
+// Search existing research
+mcp__monomind__memory_search({
+  query: "topic X",
+  namespace: "research",
+  limit: 20
 })
 ```
 
-### Reporting
-```javascript
-// Generate research report
-mcp__monomind__workflow_execute({
-  "workflowId": "research-report-generation",
-  "params": {
-    "findings": findings,
-    "format": "comprehensive"
-  }
-})
+## Monitoring
 
-// Monitor progress
-mcp__monomind__swarm_status({
-  "swarmId": "research-swarm"
-})
+```javascript
+mcp__monomind__swarm_status({ swarmId: "current" })
 ```

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

@@ -1,8 +1,62 @@
-# swarm-analysis
+---
+name: swarm-swarm-analysis
+description: Analyze swarm performance — review coordination efficiency, bottlenecks, and agent utilization for a completed swarm run
+---
 
-Command documentation for swarm-analysis in category swarm.
+# Swarm Performance Analysis
+
+Analyze how a swarm performed: coordination efficiency, agent utilization, and bottlenecks.
+
+## How to Invoke
+
+```
+Skill("swarm:swarm-analysis")
+```
+
+---
+
+## Performance Review
+
+```javascript
+// Full performance report
+mcp__monomind__performance_report({ format: "detailed" })
+
+// Identify bottlenecks
+mcp__monomind__performance_bottleneck({ component: "swarm" })
+
+// System metrics snapshot
+mcp__monomind__system_metrics({})
+
+// Coordination topology review
+mcp__monomind__coordination_metrics({})
+```
+
+## What to Analyze
+
+After a swarm completes, review:
+
+1. **Agent utilization** — were all agents busy or were some idle?
+2. **Task completion time** — which tasks took longest?
+3. **Coordination overhead** — how much time was spent coordinating vs executing?
+4. **Memory usage** — did agents share knowledge effectively?
+
+## Optimization Loop
+
+```javascript
+// Check what patterns worked
+mcp__monomind__neural_patterns({ action: "stats" })
+
+// Store lessons learned
+mcp__monomind__memory_store({
+  key: "swarm-analysis",
+  value: "what worked: hierarchical was efficient, what to improve: too many agents for small task",
+  namespace: "swarm"
+})
+```
+
+## CLI
 
-Usage:
 ```bash
-npx monomind swarm swarm-analysis [options]
+npx monomind performance report --format detailed
+npx monomind performance bottleneck --component swarm
 ```

package/.claude/commands/swarm/swarm-background.md

@@ -1,8 +1,65 @@
-# swarm-background
+---
+name: swarm-swarm-background
+description: Run swarms in background mode — start a swarm, let it work autonomously, and retrieve results later without blocking
+---
 
-Command documentation for swarm-background in category swarm.
+# Background Swarm Operations
+
+Start swarms that work autonomously without blocking the main conversation.
+
+## How to Invoke
+
+```
+Skill("swarm:swarm-background")
+```
+
+---
+
+## Pattern
+
+Background swarms work best with the Claude Code Task tool — spawn agents with `run_in_background: true`, then continue other work while they run.
+
+```javascript
+// 1. Initialize the swarm
+mcp__monomind__swarm_init({ topology: "hierarchical", maxAgents: 6, strategy: "specialized" })
+
+// 2. Spawn agents with background execution via Task tool
+// (spawn multiple agents in a single message for true parallelism)
+
+// 3. Check status later (do NOT poll — wait for notifications)
+mcp__monomind__swarm_status({ swarmId: "current" })
+```
+
+## Anti-Patterns to Avoid
+
+- **Do NOT** poll `swarm_status` in a loop — wait for agents to report back
+- **Do NOT** spawn agents one-at-a-time sequentially — spawn all in one message
+- **Do NOT** check status immediately after spawning — give agents time to work
+
+## Memory Persistence
+
+Store results from a background swarm for retrieval in future sessions:
+
+```javascript
+mcp__monomind__memory_store({
+  key: "background-swarm-results",
+  value: "summary of what was found",
+  namespace: "swarm"
+})
+```
+
+Retrieve later:
+
+```javascript
+mcp__monomind__memory_search({ query: "background swarm results", namespace: "swarm", limit: 5 })
+```
+
+## CLI
 
-Usage:
 ```bash
-npx monomind swarm swarm-background [options]
+# Start in background (returns immediately)
+npx monomind swarm start "analyze codebase" --strategy analysis &
+
+# Check later
+npx monomind swarm status
 ```

package/.claude/commands/swarm/swarm-modes.md

@@ -1,8 +1,67 @@
-# swarm-modes
+---
+name: swarm-swarm-modes
+description: Swarm topology modes reference — hierarchical, mesh, star topologies with when-to-use guidance for each coordination pattern
+---
 
-Command documentation for swarm-modes in category swarm.
+# Swarm Topology Modes
+
+Reference for choosing the right topology when initializing a swarm.
+
+## How to Invoke
+
+```
+Skill("swarm:swarm-modes")
+```
+
+---
+
+## Topologies
+
+### Hierarchical
+
+```javascript
+mcp__monomind__swarm_init({ topology: "hierarchical", maxAgents: 8, strategy: "specialized" })
+```
+
+- Coordinator agent manages worker agents
+- Best for: feature development, sequential workflows with dependencies
+- Example flow: architect → coders → tester → documenter
+
+### Mesh
+
+```javascript
+mcp__monomind__swarm_init({ topology: "mesh", maxAgents: 6, strategy: "adaptive" })
+```
+
+- All agents communicate with all others — fully connected
+- Best for: research, analysis, exploration where findings are shared across agents
+- Example flow: multiple researcher agents sharing discovered facts in real time
+
+### Star
+
+```javascript
+mcp__monomind__swarm_init({ topology: "star", maxAgents: 7, strategy: "parallel" })
+```
+
+- Central coordinator, isolated worker spokes
+- Best for: parallel independent tasks (running multiple test suites, analyzing separate modules)
+- Example flow: coordinator dispatches to 6 isolated test runner agents
+
+## Quick Selection Guide
+
+| Task | Topology | Why |
+|------|----------|-----|
+| Build a feature | hierarchical | Sequential: design → code → test |
+| Research a topic | mesh | Knowledge shared across all researchers |
+| Run test suites | star | Independent parallel execution |
+| Security audit | mesh | Cross-agent findings correlation |
+| Maintenance tasks | star | Sequential isolated steps |
+| Performance optimization | mesh | Profilers share bottleneck data |
+
+## CLI
 
-Usage:
 ```bash
-npx monomind swarm swarm-modes [options]
+npx monomind swarm init --topology hierarchical --max-agents 8
+npx monomind swarm init --topology mesh --max-agents 6
+npx monomind swarm init --topology star --max-agents 5
 ```

package/.claude/commands/swarm/swarm-monitor.md

@@ -1,8 +1,54 @@
-# swarm-monitor
+---
+name: swarm-swarm-monitor
+description: Monitor a running swarm in real-time — track agent activity, task completion, and swarm health during execution
+---
 
-Command documentation for swarm-monitor in category swarm.
+# Swarm Monitor
+
+Monitor a running swarm's progress and agent activity.
+
+## How to Invoke
+
+```
+Skill("swarm:swarm-monitor")
+```
+
+---
+
+## MCP Tools
+
+```javascript
+// Poll swarm status (call repeatedly to monitor)
+mcp__monomind__swarm_status({ swarmId: "current" })
+
+// System-level metrics
+mcp__monomind__system_metrics({})
+
+// Agent health
+mcp__monomind__agent_health({})
+
+// Agent list with status
+mcp__monomind__agent_list({})
+```
+
+## CLI
 
-Usage:
 ```bash
-npx monomind swarm swarm-monitor [options]
+# Check status
+npx monomind swarm status
+
+# List active agents
+npx monomind agent list
+
+# Agent metrics
+npx monomind agent metrics
+```
+
+## Monitoring Pattern
+
+Do NOT poll in a tight loop — check status every 30-60 seconds for long-running swarms. The swarm will report when it finishes.
+
+```javascript
+// One-time health snapshot
+mcp__monomind__swarm_health({})
 ```

package/.claude/commands/swarm/swarm-status.md

@@ -1,8 +1,44 @@
-# swarm-status
+---
+name: swarm-swarm-status
+description: Check swarm health, agent status, and progress for a running multi-agent swarm
+---
 
-Command documentation for swarm-status in category swarm.
+# Swarm Status
+
+Check the health and progress of a running swarm.
+
+## How to Invoke
+
+```
+Skill("swarm:swarm-status")
+```
+
+---
+
+## MCP Tools
+
+```javascript
+// Check current swarm
+mcp__monomind__swarm_status({ swarmId: "current" })
+
+// System-level health
+mcp__monomind__system_health({})
+
+// System metrics
+mcp__monomind__system_metrics({})
+```
+
+## CLI
 
-Usage:
 ```bash
-npx monomind swarm swarm-status [options]
+npx monomind swarm status
 ```
+
+## What to Look For
+
+- **Active agents**: count of agents currently running
+- **Task completion**: percentage of tasks finished
+- **Agent health**: any failed or stalled agents
+- **Memory usage**: memory consumption across agents
+
+If any agent is stalled, run `swarm stop` then `swarm start` to restart.