@monoes/monomindcli 1.8.0 → 1.9.0

package/.claude/commands/monomind/swarm.md

@@ -0,0 +1,161 @@
+---
+name: monomind-swarm
+description: Multi-agent swarm coordination — init, start, status, stop, scale, and coordinate agent teams
+---
+
+# Monomind Swarm Coordination
+
+Multi-agent swarm coordination with hierarchical topology, distributed memory, and load balancing.
+
+## Subcommands
+
+| Subcommand | Description |
+|---|---|
+| `init` | Initialize a new swarm (topology + strategy) |
+| `start` | Start swarm execution with an objective |
+| `status` | Show current swarm status and progress |
+| `stop` | Stop swarm execution |
+| `scale` | Scale swarm agent count up or down |
+| `coordinate` | Launch v1 15-agent hierarchical-mesh coordination |
+
+## init — Initialize a Swarm
+
+```bash
+# Default (hierarchical, 15 agents)
+npx monomind swarm init
+
+# Anti-drift configuration (recommended)
+npx monomind swarm init --topology hierarchical --max-agents 8 --strategy specialized
+
+# v1 15-agent hierarchical-mesh
+npx monomind swarm init --v1-mode
+npx monomind swarm init --topology hierarchical-mesh --max-agents 15 --strategy specialized
+```
+
+**Flags:**
+
+| Flag | Short | Default | Description |
+|---|---|---|---|
+| `--topology` | `-t` | `hierarchical` | Swarm topology (see table below) |
+| `--max-agents` | `-m` | `15` | Maximum concurrent agents |
+| `--strategy` | `-s` | — | Coordination strategy |
+| `--auto-scale` | — | `true` | Enable automatic scaling |
+| `--v1-mode` | — | `false` | Enable v1 hierarchical-mesh with 15 agents |
+
+## Topologies
+
+| Topology | Use When |
+|---|---|
+| `hierarchical` | Feature dev, bug fixes — anti-drift, tight control |
+| `hierarchical-mesh` | Large teams 10-15 agents — v1 queen + peer communication |
+| `mesh` | Research, analysis — broad coverage |
+| `star` | Parallel testing, parallel maintenance |
+| `ring` | Sequential pipeline processing |
+| `hybrid` | Dynamic topology switching |
+
+## Strategies
+
+`specialized` (anti-drift, clear roles), `balanced`, `adaptive`, `development`, `research`, `testing`, `optimization`, `maintenance`, `analysis`
+
+## start — Start Swarm Execution
+
+```bash
+# Start a development swarm
+npx monomind swarm start -o "Build REST API with authentication" -s development
+
+# Parallel research swarm
+npx monomind swarm start -o "Analyze performance bottlenecks" -s research --parallel
+```
+
+**Flags:**
+
+| Flag | Short | Default | Description |
+|---|---|---|---|
+| `--objective` | `-o` | — | Swarm objective/task (required) |
+| `--strategy` | `-s` | `development` | Execution strategy |
+| `--parallel` | `-p` | `true` | Enable parallel execution |
+| `--monitor` | — | `true` | Enable real-time monitoring |
+
+## status — Check Swarm Progress
+
+```bash
+# Overall status
+npx monomind swarm status
+
+# Status for a specific swarm ID
+npx monomind swarm status swarm-abc123
+```
+
+## stop — Stop a Swarm
+
+```bash
+# Graceful stop (saves state by default)
+npx monomind swarm stop swarm-abc123
+
+# Force immediate stop
+npx monomind swarm stop swarm-abc123 --force
+```
+
+**Flags:**
+
+| Flag | Short | Default | Description |
+|---|---|---|---|
+| `--force` | `-f` | `false` | Force immediate stop |
+| `--save-state` | — | `true` | Save state for potential resume |
+
+## scale — Adjust Agent Count
+
+```bash
+# Scale to 12 agents
+npx monomind swarm scale swarm-abc123 --agents 12
+
+# Scale a specific agent type
+npx monomind swarm scale swarm-abc123 --agents 8 --type coder
+```
+
+## coordinate — v1 15-Agent Coordination
+
+```bash
+# Full v1 15-agent hierarchical mesh
+npx monomind swarm coordinate
+
+# Subset of agents
+npx monomind swarm coordinate --agents 8
+```
+
+Activates the v1 agent roster: Queen Coordinator, Security Architect, Security Auditor, Test Architect, Core Architect, Memory Specialist, Swarm Specialist, Integration Architect, Performance Engineer, CLI Developer, Hooks Developer, MCP Specialist, Project Coordinator, Documentation Lead, DevOps Engineer.
+
+## MCP Tools
+
+```javascript
+// Initialize swarm
+mcp__monomind__swarm_init({ topology: "hierarchical", maxAgents: 8, strategy: "specialized" })
+
+// Check status
+mcp__monomind__swarm_status({})
+
+// Health check
+mcp__monomind__swarm_health({})
+
+// Shutdown swarm
+mcp__monomind__swarm_shutdown({})
+```
+
+## Agent Team Routing
+
+| Task Type | Agents | Topology |
+|---|---|---|
+| Bug Fix | coordinator, researcher, coder, tester | hierarchical |
+| Feature | coordinator, architect, coder, tester, reviewer | hierarchical |
+| Refactor | coordinator, architect, coder, reviewer | hierarchical |
+| Performance | coordinator, perf-engineer, coder | hierarchical |
+| Security | coordinator, security-architect, auditor | hierarchical |
+| Research | coordinator, researcher x4, analyst x2 | mesh |
+
+## See Also
+
+- `npx monomind agent spawn` — Spawn individual agents
+- `npx monomind hive-mind init` — Byzantine fault-tolerant consensus
+- `/mastermind` — Interactive swarm topology selection
+
+Documentation: https://github.com/nokhodian/monomind

package/.claude/commands/monomind/understand.md

@@ -0,0 +1,148 @@
+---
+name: monomind:understand
+description: "Monomind — Run semantic enrichment on the current project's monograph knowledge graph"
+---
+
+# /monomind:understand — Semantic Enrichment
+
+Enriches the current project's monograph knowledge graph with LLM-generated summaries,
+architectural layers, and semantic relationships.
+
+Parse `$ARGUMENTS` for the flags below.
+
+## Parse Arguments
+
+Parse `$ARGUMENTS` for these optional flags:
+
+- `--dir <path>`    — project directory to analyze (default: current working directory)
+- `--db <path>`     — path to monograph.db (default: `<dir>/.monomind/monograph.db`)
+- `--import`        — import an existing graph.json only (skip running /understand)
+- `--graph <path>`  — explicit path to a UA graph.json file to import
+- `--full`          — force full re-analysis even if graph.json is recent
+- `--dry-run`       — show what would happen without writing to DB
+
+If no flags, treat any bare path argument as `--dir`.
+
+---
+
+## Step 1: Locate project and monograph DB
+
+```bash
+DIR="${ARGUMENTS_dir:-$(pwd)}"
+DB="${ARGUMENTS_db:-$DIR/.monomind/monograph.db}"
+```
+
+1. Resolve `DIR` to an absolute path.
+2. Check that `$DB` exists. If not, tell the user:
+   > monograph.db not found at `$DB`. Build the graph first:
+   > ```bash
+   > npx monomind monograph build
+   > ```
+   > Then re-run `/monomind:understand`.
+   And STOP.
+
+---
+
+## Step 2: Check for existing UA graph.json
+
+Look for `$DIR/.understand/knowledge-graph.json`, `$DIR/.understand/graph.json`, and `$DIR/.ua/graph.json` (in that order).
+
+If `--graph <path>` was supplied, use that path instead.
+
+**If a graph.json is found AND `--full` was NOT set:**
+
+Report the file age:
+```
+Found graph.json (X hours old) — importing into monograph…
+```
+
+Jump to **Step 4: Import**.
+
+**If no graph.json is found OR `--full` was set:**
+
+Proceed to **Step 3: Run understand analysis**.
+
+---
+
+## Step 3: Run understand analysis
+
+Locate the understand plugin. Check these paths in order:
+1. `/Users/morteza/Desktop/tools/knowledgegraph/Understand-Anything/understand-anything-plugin`
+2. `$HOME/Desktop/tools/knowledgegraph/Understand-Anything/understand-anything-plugin`
+3. `$UA_PLUGIN_DIR` (if set)
+
+If the plugin is NOT found, tell the user:
+> understand plugin not found.
+> Clone it to a sibling of this project or set `UA_PLUGIN_DIR`:
+> ```bash
+> git clone https://github.com/nicholasgasior/understand-anything ~/Desktop/tools/knowledgegraph/Understand-Anything
+> ```
+And STOP.
+
+**If found:**
+
+Use the Agent tool to run the `/understand` skill on `$DIR`.
+The skill produces `.understand/graph.json` in the target directory.
+
+Instruct the spawned agent:
+- Project directory: `$DIR`
+- Run the full `/understand` pipeline (project-scanner → file-analyzer → architecture-analyzer → tour-builder)
+- Save the resulting graph.json to `$DIR/.understand/graph.json`
+- Report back when done with node/edge/layer counts
+
+Wait for completion before proceeding.
+
+---
+
+## Step 4: Import graph.json into monograph DB
+
+Run the import script:
+
+```bash
+node /path/to/monobrain/scripts/ua-import.mjs "$GRAPH_JSON" "$DB"
+```
+
+Where:
+- `$GRAPH_JSON` is the graph.json path (found in Step 2 or produced in Step 3)
+- `$DB` is the monograph.db path
+
+If `--dry-run` was set, instead read graph.json and report what WOULD be written:
+- Number of nodes to enrich / insert
+- Number of edges to add
+- Layers that would become communities
+Do NOT write to the DB.
+
+---
+
+## Step 5: Report results
+
+After import completes, show a summary table:
+
+```
+╔══════════════════════════════════════════╗
+║  /monomind:understand — Enrichment Done  ║
+╠══════════════════════════════════════════╣
+║  DB:              .monomind/monograph.db ║
+║  Nodes enriched:  <N>                    ║
+║  Nodes inserted:  <N>                    ║
+║  Edges added:     <N>                    ║
+║  Communities:     <N> (from UA layers)   ║
+╚══════════════════════════════════════════╝
+```
+
+Then tell the user:
+> The monograph graph is now enriched with semantic summaries and architectural layers.
+> Open the Monomind control panel and click **Monograph → GRAPH** to see multi-color layers.
+> Each color now represents an architectural layer (API, Service, Data, UI, etc.).
+
+If any nodes were skipped (unresolved edges), report the count but do NOT treat it as an error.
+
+To repeat this command on a schedule, wrap it with `/monomind:repeat`.
+
+---
+
+## Error Handling
+
+- If `ua-import.mjs` exits non-zero, show stderr and suggest running `pnpm install` from the monobrain root.
+- If graph.json is malformed JSON, report the parse error and suggest re-running `/understand`.
+- All errors are non-fatal to the main session — report and return cleanly.

package/.claude/commands/optimization/README.md

@@ -1,9 +1,73 @@
+---
+name: optimization:README
+description: Optimization skills index — swarm topology selection, parallel execution patterns, and system-level performance tuning
+---
+
 # Optimization Commands
 
-Commands for optimization operations in Monomind.
+Guides and commands for optimizing Monomind performance — swarm topology, parallel execution, and system-level tuning.
+
+## Real CLI Commands
+
+| Command | Description |
+|---|---|
+| `performance optimize` | Analyze and apply system optimizations (memory/CPU/latency) |
+| `performance bottleneck` | Find performance bottlenecks |
+| `performance benchmark` | Run benchmark suites (WASM/neural/memory/search) |
+| `performance metrics` | View performance metrics over time |
+| `neural optimize` | Quantize or compact neural model weights |
+| `swarm init --topology` | Configure swarm topology for performance |
+
+## Quick Reference
+
+```bash
+# Find what's slow
+npx monomind performance bottleneck
+
+# Get optimization recommendations (no changes)
+npx monomind performance optimize --dry-run
+
+# Apply all optimizations
+npx monomind performance optimize --target all --apply
+
+# Benchmark all subsystems
+npx monomind performance benchmark --suite all
+
+# Neural model quantization
+npx monomind neural optimize --method quantize
+```
+
+## Files
+
+- [auto-topology.md](./auto-topology.md) — Automatic topology selection and swarm configuration
+- [parallel-execution.md](./parallel-execution.md) — Parallel agent execution patterns with Task tool
+- [performance-optimize.md](./performance-optimize.md) — `performance optimize` CLI reference
+
+## MCP Tools
+
+| Tool | Purpose |
+|---|---|
+| `mcp__monomind__performance_optimize` | Apply performance optimizations |
+| `mcp__monomind__performance_benchmark` | Run benchmarks |
+| `mcp__monomind__performance_metrics` | Get performance metrics |
+| `mcp__monomind__performance_bottleneck` | Detect bottlenecks |
+| `mcp__monomind__performance_profile` | CPU/memory profiling |
+| `mcp__monomind__coordination_topology` | Optimize swarm topology |
+| `mcp__monomind__neural_optimize` | Neural model optimization |
+
+## Performance Targets
+
+| Metric | Target |
+|---|---|
+| Flash Attention | 2.49x–7.47x speedup |
+| HNSW Search | 150x–12,500x faster |
+| Memory Reduction | 50–75% with quantization |
+| MCP Response | <100ms |
+| CLI Startup | <500ms |
 
-## Available Commands
+## See Also
 
-- [topology-optimize](./topology-optimize.md)
-- [parallel-execute](./parallel-execute.md)
-- [cache-manage](./cache-manage.md)
+- `performance` — full performance command set
+- `neural` — neural training and optimization
+- `memory compress` — memory-level optimization
+- `hooks metrics` — intelligence system metrics

package/.claude/commands/optimization/auto-topology.md

@@ -1,62 +1,85 @@
-# Automatic Topology Selection
+---
+name: optimization:auto-topology
+description: Automatically select the optimal swarm topology based on task complexity — use pre-task hook recommendations, swarm init flags, and performance optimize CLI
+---
 
-## Purpose
-Automatically select the optimal swarm topology based on task complexity analysis.
+# Auto Topology Selection
 
-## How It Works
+Automatically select the optimal swarm topology based on task complexity so you don't have to configure it manually.
 
-### 1. Task Analysis
-The system analyzes your task description to determine:
-- Complexity level (simple/medium/complex)
-- Required agent types
-- Estimated duration
-- Resource requirements
+## How It Works
 
-### 2. Topology Selection
-Based on analysis, it selects:
-- **Star**: For simple, centralized tasks
-- **Mesh**: For medium complexity with flexibility needs
-- **Hierarchical**: For complex tasks requiring structure
-- **Ring**: For sequential processing workflows
+### 1. Get a Routing Recommendation
 
-### 3. Example Usage
+Before spawning agents, run the `pre-task` hook. It analyzes task complexity and recommends a topology:
 
-**Simple Task:**
+```bash
+npx monomind hooks pre-task -d "Refactor authentication system with JWT, add tests, update docs"
 ```
-Tool: mcp__monomind__task_orchestrate
-Parameters: {"task": "Fix typo in README.md"}
-Result: Automatically uses star topology with single agent
+
+Output includes `[TASK_MODEL_RECOMMENDATION] Use model="sonnet"` and agent/topology suggestions.
+
+### 2. Initialize the Swarm With the Recommended Topology
+
+```bash
+# Simple/medium tasks — hierarchical (anti-drift, tight control)
+npx monomind swarm init --topology hierarchical --max-agents 6 --strategy specialized
+
+# Complex multi-domain tasks — hierarchical-mesh (peer communication + queen)
+npx monomind swarm init --topology hierarchical-mesh --max-agents 12 --strategy specialized
 ```
 
-**Complex Task:**
+### Topology Selection Guide
+
+| Complexity | Agents Needed | Recommended Topology |
+|---|---|---|
+| Simple (single file) | 1–2 | `star` — skip swarm, use Edit tool directly |
+| Medium | 3–5 | `hierarchical` |
+| Complex (multi-module) | 6–8 | `hierarchical` |
+| Large (10+ agents) | 10–15 | `hierarchical-mesh` |
+| Sequential pipeline | any | `ring` |
+
+## Optimize Existing Swarm Topology
+
+If a swarm is already running, optimize its topology via the coordination MCP tool:
+
+```javascript
+mcp__monomind__coordination_topology({
+  swarmId: "current",
+  optimize: true
+})
 ```
-Tool: mcp__monomind__task_orchestrate
-Parameters: {"task": "Refactor authentication system with JWT, add tests, update documentation"}
-Result: Automatically uses hierarchical topology with architect, coder, and tester agents
+
+Or via the performance CLI:
+
+```bash
+# Analyze and recommend optimizations (dry run)
+npx monomind performance optimize --target all --dry-run
+
+# Apply recommended optimizations
+npx monomind performance optimize --target all --apply
 ```
 
-## Benefits
-- 🎯 Optimal performance for each task type
-- 🤖 Automatic agent assignment
-- ⚡ Reduced setup time
-- 📊 Better resource utilization
+## Hook Integration
+
+`pre-task` fires automatically if wired in `settings.json`:
 
-## Hook Configuration
-The pre-task hook automatically handles topology selection:
 ```json
 {
-  "command": "npx monomind hook pre-task --optimize-topology"
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "^Task$",
+      "hooks": [{
+        "type": "command",
+        "command": "npx monomind hooks pre-task -d '${tool.params.description}'"
+      }]
+    }]
+  }
 }
 ```
 
-## Direct Optimization
-```
-Tool: mcp__monomind__topology_optimize
-Parameters: {"swarmId": "current"}
-```
+## See Also
 
-## CLI Usage
-```bash
-# Auto-optimize topology via CLI
-npx monomind optimize topology
-```
+- `swarm init` — initialize swarm with explicit topology
+- `performance optimize` — system-level performance tuning
+- `hooks pre-task` — get routing and topology recommendations

package/.claude/commands/optimization/parallel-execution.md

@@ -1,50 +1,76 @@
+---
+name: optimization:parallel-execution
+description: Execute independent subtasks in parallel using Claude Code's Task tool — spawn all agents in one message, use swarm coordination, and monitor with swarm_status
+---
+
 # Parallel Task Execution
 
-## Purpose
-Execute independent subtasks in parallel for maximum efficiency.
+Execute independent subtasks in parallel for maximum throughput. Parallel execution is handled by Claude Code's Task tool — not a CLI command.
 
-## Coordination Strategy
+## The Pattern: Spawn All Agents in One Message
 
-### 1. Task Decomposition
-```
-Tool: mcp__monomind__task_orchestrate
-Parameters: {
-  "task": "Build complete REST API with auth, CRUD operations, and tests",
-  "strategy": "parallel",
-  "maxAgents": 8
-}
-```
+```javascript
+// Initialize swarm coordination
+// npx monomind swarm init --topology hierarchical --max-agents 8 --strategy specialized
 
-### 2. Parallel Workflows
-The system automatically:
-- Identifies independent components
-- Assigns specialized agents
-- Executes in parallel where possible
-- Synchronizes at dependency points
-
-### 3. Example Breakdown
-For the REST API task:
-- **Agent 1 (Architect)**: Design API structure
-- **Agent 2-3 (Coders)**: Implement auth & CRUD in parallel
-- **Agent 4 (Tester)**: Write tests as features complete
-- **Agent 5 (Documenter)**: Update docs continuously
-
-## CLI Usage
-```bash
-# Execute parallel tasks via CLI
-npx monomind parallel "Build REST API" --max-agents 8
+// Then spawn ALL agents in ONE message with run_in_background: true
+Task({ prompt: "Design API structure and document decisions", subagent_type: "system-architect", run_in_background: true });
+Task({ prompt: "Implement auth endpoints following the architecture", subagent_type: "coder", run_in_background: true });
+Task({ prompt: "Implement CRUD endpoints in parallel with auth", subagent_type: "coder", run_in_background: true });
+Task({ prompt: "Write tests as features complete", subagent_type: "tester", run_in_background: true });
+Task({ prompt: "Review code quality and security", subagent_type: "reviewer", run_in_background: true });
 ```
 
-## Performance Gains
-- 🚀 2.8-4.4x faster execution
-- 💪 Optimal CPU utilization
-- 🔄 Automatic load balancing
-- 📈 Linear scalability with agents
+After spawning, **stop and wait** — do not poll or check status. Agents report back when done.
+
+## Coordination via MCP
 
-## Monitoring
+```javascript
+// Orchestrate a parallel task plan
+mcp__monomind__coordination_orchestrate({
+  task: "Build REST API with auth, CRUD, and tests",
+  strategy: "parallel",
+  maxAgents: 8
+})
 ```
-Tool: mcp__monomind__swarm_monitor
-Parameters: {"interval": 1000, "swarmId": "current"}
+
+## Task Decomposition Principles
+
+1. **Identify independent components** — what has no dependency on others?
+2. **Assign by specialization** — coder for implementation, tester for tests, architect for design
+3. **Synchronize at dependency points** — one agent waits for another's output before proceeding
+4. **Keep tasks focused** — one clear objective per agent, not a list of things
+
+## Example Breakdown for a Feature
+
+| Agent | Task | Depends On |
+|---|---|---|
+| Architect | Design data model + API contract | — |
+| Coder A | Implement auth module | Architect |
+| Coder B | Implement CRUD module | Architect |
+| Tester | Write integration tests | Coder A + B |
+| Reviewer | Code review + security check | Coder A + B |
+
+## Performance Impact
+
+With 5 parallel agents on a typical feature:
+- Sequential: ~30 minutes
+- Parallel: ~10–12 minutes (2.5–3x faster)
+
+The bottleneck shifts to synchronization points, not raw execution time.
+
+## Monitor Active Execution
+
+```bash
+# Check current swarm and agent status
+npx monomind status --watch
+
+# Or via MCP
+mcp__monomind__swarm_status({ includeMetrics: true })
 ```
 
-Watch real-time parallel execution progress!
+## See Also
+
+- `swarm init` — configure topology before spawning
+- `status` — monitor parallel execution progress
+- `hooks pre-task` — get agent recommendations before spawning