@monoes/monomindcli 1.8.0 → 1.9.0

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

@@ -1,8 +1,73 @@
-# hive-mind-memory
+---
+name: hive-mind:hive-mind-memory
+---
 
-Command documentation for hive-mind-memory in category hive-mind.
+# hive-mind memory
 
-Usage:
+Access and manage hive shared memory — key-value store accessible to all agents in the hive.
+
+## Usage
 ```bash
-npx monomind hive-mind hive-mind-memory [options]
+npx monomind hive-mind memory [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--action` | `-a` | string | `list` | Action: `get`, `set`, `delete`, `list` |
+| `--key` | `-k` | string | — | Memory key (required for `get`, `set`, `delete`) |
+| `--value` | `-v` | string | — | Value to store (required for `set`) |
+| `--format` | — | string | — | Output format: `json` |
+
+## Examples
+
+```bash
+# List all keys in shared memory
+npx monomind hive-mind memory
+
+# Store a value
+npx monomind hive-mind memory -a set -k "project-goal" -v "Build auth module"
+
+# Retrieve a value
+npx monomind hive-mind memory -a get -k "project-goal"
+
+# Delete a key
+npx monomind hive-mind memory -a delete -k "project-goal"
+
+# List all keys as JSON
+npx monomind hive-mind memory -a list --format json
+```
+
+## Actions
+
+- **`list`** — Show all keys currently in shared memory with count (default)
+- **`get`** — Retrieve the value at a key (requires `--key`)
+- **`set`** — Store a value at a key (requires `--key` and `--value`)
+- **`delete`** — Remove a key from shared memory (requires `--key`)
+
+## Relationship to `monomind memory`
+
+`hive-mind memory` operates on the **hive's shared memory namespace** — values here are visible to all agents coordinating in the current hive. This is distinct from `npx monomind memory` which operates on the global AgentDB.
+
+Use hive memory for transient inter-agent coordination data (task results, intermediate state). Use global memory for patterns and knowledge that should persist across sessions.
+
+## MCP Tool
+
+```javascript
+// List keys
+mcp__monomind__hive-mind_memory({ action: "list" })
+
+// Set a value
+mcp__monomind__hive-mind_memory({
+  action: "set",
+  key: "project-goal",
+  value: "Build auth module"
+})
+
+// Get a value
+mcp__monomind__hive-mind_memory({ action: "get", key: "project-goal" })
+
+// Delete a key
+mcp__monomind__hive-mind_memory({ action: "delete", key: "project-goal" })
 ```

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

@@ -1,21 +1,82 @@
-# hive-mind-spawn
+---
+name: hive-mind:hive-mind-spawn
+---
 
-Spawn a Hive Mind swarm with queen-led coordination.
+# hive-mind spawn
+
+Spawn worker agents into the hive, or launch Claude Code as the Queen coordinator.
 
 ## Usage
 ```bash
-npx monomind hive-mind spawn <objective> [options]
+npx monomind hive-mind spawn [options]
 ```
 
 ## Options
-- `--queen-type <type>` - Queen type (strategic, tactical, adaptive)
-- `--max-workers <n>` - Maximum worker agents
-- `--consensus <type>` - Consensus algorithm
-- `--claude` - Generate Claude Code spawn commands
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--count` | `-n` | number | `1` | Number of workers to spawn |
+| `--role` | `-r` | string | `worker` | Worker role: `worker`, `specialist`, `scout` |
+| `--type` | `-t` | string | `worker` | Agent type (matches agent registry types) |
+| `--prefix` | `-p` | string | `hive-worker` | Prefix for generated worker IDs |
+| `--claude` | — | boolean | `false` | Launch Claude Code as the Queen coordinator |
+| `--objective` | `-o` | string | — | Objective for the hive (required with `--claude`) |
+| `--dry-run` | — | boolean | `false` | Preview what would happen without launching |
+| `--non-interactive` | — | boolean | `false` | Run Claude Code in non-interactive (pipe) mode |
+| `--dangerously-skip-permissions` | — | boolean | `true` | Skip Claude Code permission prompts |
+| `--no-auto-permissions` | — | boolean | `false` | Disable automatic permission skipping |
 
 ## Examples
+
 ```bash
-npx monomind hive-mind spawn "Build API"
-npx monomind hive-mind spawn "Research patterns" --queen-type adaptive
-npx monomind hive-mind spawn "Build service" --claude
+# Spawn 5 default workers
+npx monomind hive-mind spawn -n 5
+
+# Spawn 3 specialists
+npx monomind hive-mind spawn -n 3 -r specialist
+
+# Spawn a coder agent with custom ID prefix
+npx monomind hive-mind spawn -t coder -p my-coder
+
+# Launch Claude Code as Queen with a specific objective
+npx monomind hive-mind spawn --claude -o "Build a REST API with authentication"
+
+# Spawn 5 workers AND launch Claude Code as Queen
+npx monomind hive-mind spawn -n 5 --claude -o "Research AI coordination patterns"
+
+# Preview what would happen without launching
+npx monomind hive-mind spawn -n 3 --claude -o "Test objective" --dry-run
+
+# Non-interactive mode (for CI/scripts)
+npx monomind hive-mind spawn --claude -o "Run security audit" --non-interactive
+```
+
+## The `--claude` Flag
+
+When `--claude` is used, the CLI:
+
+1. Spawns the requested worker agents in the hive
+2. Generates a comprehensive Hive Mind coordination prompt that includes:
+   - Swarm ID, topology, consensus algorithm
+   - All worker IDs and their roles
+   - Full list of MCP tools available for coordination
+   - The objective and execution protocol
+3. Saves the prompt to `.hive-mind/sessions/hive-mind-prompt-<id>.txt`
+4. Launches `claude --dangerously-skip-permissions <prompt>` so Claude acts as the Queen
+
+The Queen Claude instance uses MCP tools (`mcp__monomind__hive-mind_*`, `mcp__monomind__coordination_orchestrate`, etc.) to coordinate all worker agents.
+
+**Requirements:**
+- `--objective` / `-o` must be set (the Queen needs a goal)
+- Claude Code CLI must be installed: `npm install -g @anthropic-ai/claude-code`
+
+## MCP Tool
+
+```javascript
+mcp__monomind__hive-mind_spawn({
+  count: 5,
+  role: "worker",
+  type: "coder",
+  prefix: "hive-worker"
+})
 ```

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

@@ -1,8 +1,56 @@
-# hive-mind-status
+---
+name: hive-mind:hive-mind-status
+---
 
-Command documentation for hive-mind-status in category hive-mind.
+# hive-mind status
+
+Show hive mind status including queen, workers, and optional detailed metrics.
+
+## Usage
+```bash
+npx monomind hive-mind status [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--detailed` | `-d` | boolean | `false` | Include metrics (task counts, avg time, consensus rounds, memory) and health breakdown |
+| `--watch` | `-w` | boolean | `false` | Watch for changes and refresh |
+| `--format` | — | string | — | Output format: `json` |
+
+## Examples
 
-Usage:
 ```bash
-npx monomind hive-mind hive-mind-status [options]
+# Basic status
+npx monomind hive-mind status
+
+# Full metrics and health breakdown
+npx monomind hive-mind status --detailed
+
+# Watch mode (refreshes on change)
+npx monomind hive-mind status --watch
+
+# JSON output for scripting
+npx monomind hive-mind status --format json
+```
+
+## Output
+
+Basic status shows:
+- Hive ID, status (active / idle / degraded / offline), topology, consensus
+- Queen agent ID, status, load %, and queued task count
+- Worker table: ID, type, status, current task, tasks completed
+
+`--detailed` adds:
+- Metrics table: total tasks, completed, failed, avg task time, consensus rounds, memory usage
+- Health breakdown: overall, queen, workers, consensus, memory
+
+## MCP Tool
+
+```javascript
+mcp__monomind__hive-mind_status({
+  includeMetrics: true,  // set by --detailed
+  includeWorkers: true
+})
 ```

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

@@ -1,8 +1,55 @@
-# hive-mind-stop
+---
+name: hive-mind:hive-mind-stop
+---
 
-Command documentation for hive-mind-stop in category hive-mind.
+# hive-mind shutdown
 
-Usage:
+Gracefully shutdown the hive mind, terminating all agents.
+
+## Usage
 ```bash
-npx monomind hive-mind hive-mind-stop [options]
+npx monomind hive-mind shutdown [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--force` | `-f` | boolean | `false` | Force immediate shutdown without confirmation |
+| `--save-state` | `-s` | boolean | `true` | Save hive state before shutdown (default: on) |
+
+## Examples
+
+```bash
+# Graceful shutdown with confirmation prompt
+npx monomind hive-mind shutdown
+
+# Force shutdown immediately, no prompt
+npx monomind hive-mind shutdown --force
+
+# Shutdown and save state for later recovery
+npx monomind hive-mind shutdown --save-state
+
+# Force shutdown without saving state
+npx monomind hive-mind shutdown --force --save-state false
+```
+
+## Behavior
+
+Without `--force`, the CLI prompts for confirmation before proceeding.
+
+The shutdown report includes:
+- Number of agents terminated
+- Whether state was saved
+- Shutdown timestamp
+
+When `--save-state` is enabled (default), hive state is persisted and can be referenced in future sessions via `monomind session list`.
+
+## MCP Tool
+
+```javascript
+mcp__monomind__hive-mind_shutdown({
+  force: false,
+  saveState: true
+})
 ```

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

@@ -1,27 +1,87 @@
+---
+name: hive-mind:hive-mind
+---
+
 # hive-mind
 
-Hive Mind collective intelligence system for advanced swarm coordination.
+Queen-led consensus-based multi-agent coordination system.
 
 ## Usage
 ```bash
-npx monomind hive-mind [subcommand] [options]
+npx monomind 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
+| Subcommand | Description |
+|---|---|
+| `init` | Initialize hive mind with topology and consensus settings |
+| `spawn` | Spawn worker agents; use `--claude` to launch Claude Code as Queen |
+| `status` | Show hive status, workers, and metrics |
+| `task` | Submit a task to the hive for distributed execution |
+| `join` | Add an existing agent to the hive |
+| `leave` | Remove an agent from the hive |
+| `consensus` | Manage consensus proposals and voting |
+| `broadcast` | Broadcast a message to all workers |
+| `memory` | Access and manage hive shared memory |
+| `optimize-memory` | Optimize hive memory patterns and consolidation |
+| `shutdown` | Gracefully shutdown the hive mind |
+
+## Topologies
+
+| Topology | Description |
+|---|---|
+| `hierarchical` | Queen controls workers directly — tight coordination for small teams |
+| `mesh` | Peer-to-peer coordination among all agents |
+| `hierarchical-mesh` | Queen + peer communication — recommended for 10+ agents |
+| `adaptive` | Dynamic topology based on task load |
+
+## Consensus Strategies
+
+| Strategy | Description |
+|---|---|
+| `byzantine` | BFT — tolerates f < n/3 faulty agents (default) |
+| `raft` | Leader-based — tolerates f < n/2 |
+| `gossip` | Eventually consistent, scales well |
+| `crdt` | Conflict-free replicated data types |
+| `quorum` | Simple majority voting |
+
+## Quick Start
+
 ```bash
-# Initialize hive mind
-npx monomind hive-mind init
+# 1. Initialize hive with recommended topology
+npx monomind hive-mind init -t hierarchical-mesh -c byzantine
+
+# 2. Spawn workers
+npx monomind hive-mind spawn -n 5 -r specialist
 
-# Spawn swarm
-npx monomind hive-mind spawn "Build microservices"
+# 3. (Optional) Launch Claude Code as the Queen coordinator
+npx monomind hive-mind spawn --claude -o "Build a REST API with auth"
 
-# Check status
-npx monomind hive-mind status
+# 4. Check status
+npx monomind hive-mind status --detailed
+
+# 5. Submit a task
+npx monomind hive-mind task -d "Implement authentication module" -p high
+
+# 6. Shutdown when done
+npx monomind hive-mind shutdown --save-state
+```
+
+## MCP Tools
+
+All subcommands call their corresponding MCP tool:
+
+```
+mcp__monomind__hive-mind_init
+mcp__monomind__hive-mind_spawn
+mcp__monomind__hive-mind_status
+mcp__monomind__hive-mind_task
+mcp__monomind__hive-mind_join
+mcp__monomind__hive-mind_leave
+mcp__monomind__hive-mind_consensus
+mcp__monomind__hive-mind_broadcast
+mcp__monomind__hive-mind_memory
+mcp__monomind__hive-mind_optimize-memory
+mcp__monomind__hive-mind_shutdown
 ```

package/.claude/commands/hooks/README.md

@@ -1,11 +1,66 @@
+---
+name: hooks:README
+---
+
 # Hooks Commands
 
-Commands for hooks operations in Monomind.
+Self-learning hooks system for intelligent workflow automation. Invoked as `npx monomind hooks <subcommand>`.
+
+## Commands (invoke as slash commands)
+
+- [overview](./overview.md) — hooks system overview, Claude Code integration, settings.json config
+- [setup](./setup.md) — how to configure hooks in settings.json
+- [pre-edit](./pre-edit.md) — get context and agent suggestions before editing a file
+- [post-edit](./post-edit.md) — record edit outcome for learning
+- [pre-task](./pre-task.md) — register task start, get agent suggestions and model routing
+- [post-task](./post-task.md) — record task completion for pattern learning
+- [session-end](./session-end.md) — end session and persist state
+
+## All Real Subcommands (25+)
+
+```
+pre-edit          Get context and agent suggestions before editing a file
+post-edit         Record editing outcome for neural pattern learning
+pre-command       Assess risk before executing a command
+post-command      Record command execution outcome
+pre-task          Register task start and get agent suggestions + model routing
+post-task         Record task completion for learning
+session-end       End current session and persist state
+session-restore   Restore a previous session
+route             Route task to optimal agent using learned patterns
+explain           Explain routing decision with transparency
+pretrain          Bootstrap intelligence from repository (4-step pipeline + embeddings)
+build-agents      Generate optimized agent configs from pretrain data
+metrics           View learning metrics dashboard
+transfer          Transfer patterns via IPFS registry or from another project
+list              List all registered hooks
+worker            Background worker management (12 workers)
+progress          Check v1 implementation progress
+statusline        Generate dynamic statusline for Claude Code display
+coverage-route    Route tasks based on test coverage gaps
+coverage-suggest  Suggest coverage improvements for a path
+coverage-gaps     List all coverage gaps with priorities
+token-optimize    Token optimization (30-50% savings)
+model-route       Route to optimal model (haiku/sonnet/opus)
+model-outcome     Record model routing outcome
+model-stats       View model routing statistics
+intelligence      RuVector intelligence system (trajectory, patterns, stats)
+notify            Send notification with level and message
+worker list       List all 12 background workers
+worker dispatch   Dispatch a specific worker
+worker status     Check worker status
+worker detect     Detect worker triggers from a prompt
+worker cancel     Cancel a running worker
+```
 
-## Available Commands
+## Real MCP Tools
 
-- [pre-task](./pre-task.md)
-- [post-task](./post-task.md)
-- [pre-edit](./pre-edit.md)
-- [post-edit](./post-edit.md)
-- [session-end](./session-end.md)
+- `mcp__monomind__hooks_pre_edit` / `hooks_post_edit`
+- `mcp__monomind__hooks_pre_command` / `hooks_post_command`
+- `mcp__monomind__hooks_pre_task` / `hooks_post_task`
+- `mcp__monomind__hooks_session_end` / `hooks_session_restore`
+- `mcp__monomind__hooks_route` / `hooks_explain`
+- `mcp__monomind__hooks_pretrain` / `hooks_build_agents`
+- `mcp__monomind__hooks_metrics` / `hooks_transfer`
+- `mcp__monomind__hooks_intelligence` / `hooks_notify`
+- `mcp__monomind__hooks_worker_list` / `hooks_worker_dispatch` / etc.

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

@@ -1,33 +1,70 @@
-# Claude Code Hooks for monomind
+---
+name: hooks:overview
+---
 
-## Purpose
-Automatically coordinate, format, and learn from Claude Code operations using hooks.
+# Hooks System Overview
 
-## Available Hooks
+Self-learning hooks for intelligent workflow automation. Hooks connect Claude Code tool events to Monomind's pattern learning, agent routing, and session persistence.
 
-### Pre-Operation Hooks
-- **pre-edit**: Validate and assign agents before file modifications
-- **pre-bash**: Check command safety and resource requirements
-- **pre-task**: Auto-spawn agents for complex tasks
+## How It Works
 
-### Post-Operation Hooks
-- **post-edit**: Auto-format code and train neural patterns
-- **post-bash**: Log execution and update metrics
-- **post-search**: Cache results and improve search patterns
+Claude Code fires hook events (PreToolUse, PostToolUse, etc.) which trigger `npx monomind hooks <subcommand>` commands. The hooks system:
 
-### MCP Integration Hooks
-- **mcp-initialized**: Persist swarm configuration
-- **agent-spawned**: Update agent roster
-- **task-orchestrated**: Monitor task progress
-- **neural-trained**: Save pattern improvements
+1. **Routes** tasks to optimal agents using learned patterns
+2. **Records** outcomes (edits, commands, tasks) for neural pattern learning
+3. **Persists** session state across conversations
+4. **Bootstraps** intelligence from repository code
 
-### Session Hooks
-- **notify**: Custom notifications with swarm status
-- **session-end**: Generate summary and save state
-- **session-restore**: Load previous session state
+## CLI Subcommands
 
-## Configuration
-Hooks are configured in `.claude/settings.json`:
+All hooks are invoked as `npx monomind hooks <subcommand>`:
+
+### Lifecycle Hooks
+| Subcommand | Purpose |
+|---|---|
+| `pre-edit` | Context + agent suggestions before file edit |
+| `post-edit` | Record edit outcome for learning |
+| `pre-command` | Risk assessment before running a command |
+| `post-command` | Record command outcome |
+| `pre-task` | Register task start, get agent suggestions + model routing |
+| `post-task` | Record task completion |
+| `session-end` | End session and persist state |
+| `session-restore` | Restore a previous session |
+
+### Intelligence & Routing
+| Subcommand | Purpose |
+|---|---|
+| `route` | Route task to optimal agent |
+| `explain` | Explain routing decision |
+| `pretrain` | Bootstrap intelligence from repo (4-step pipeline) |
+| `build-agents` | Generate optimized agent configs from pretrain data |
+| `metrics` | View learning metrics dashboard |
+| `model-route` | Route to optimal model (haiku/sonnet/opus) |
+| `model-outcome` | Record model routing result |
+| `model-stats` | View model routing statistics |
+
+### Coverage & Token Tools
+| Subcommand | Purpose |
+|---|---|
+| `coverage-route` | Route based on test coverage gaps |
+| `coverage-suggest` | Suggest coverage improvements |
+| `coverage-gaps` | List all coverage gaps with priorities |
+| `token-optimize` | Token optimization (30-50% savings) |
+
+### Workers & Utilities
+| Subcommand | Purpose |
+|---|---|
+| `worker` | Background worker management (12 workers) |
+| `intelligence` | RuVector trajectory and pattern system |
+| `notify` | Send a notification |
+| `statusline` | Generate dynamic statusline display |
+| `list` | List all registered hooks |
+| `progress` | Check v1 implementation progress |
+| `transfer` | Transfer patterns via IPFS or from another project |
+
+## Claude Code Integration
+
+Configure in `.claude/settings.json`:
 
 ```json
 {
@@ -37,7 +74,23 @@ Hooks are configured in `.claude/settings.json`:
         "matcher": "^(Write|Edit|MultiEdit)$",
         "hooks": [{
           "type": "command",
-          "command": "npx monomind hook pre-edit --file '${tool.params.file_path}'"
+          "command": "npx monomind hooks pre-edit --file '${tool.params.file_path}'"
+        }]
+      },
+      {
+        "matcher": "^Bash$",
+        "hooks": [{
+          "type": "command",
+          "command": "npx monomind hooks pre-command --command '${tool.params.command}'"
+        }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(Write|Edit|MultiEdit)$",
+        "hooks": [{
+          "type": "command",
+          "command": "npx monomind hooks post-edit --file '${tool.params.file_path}' --success true"
         }]
       }
     ]
@@ -45,14 +98,20 @@ Hooks are configured in `.claude/settings.json`:
 }
 ```
 
-## Benefits
-- 🤖 Automatic agent assignment based on file type
-- 🎨 Consistent code formatting
-- 🧠 Continuous neural pattern improvement
-- 💾 Cross-session memory persistence
-- 📊 Performance metrics tracking
-
-## See Also
-- [Pre-Edit Hook](./pre-edit.md)
-- [Post-Edit Hook](./post-edit.md)
-- [Session End Hook](./session-end.md)
+## 4-Step Intelligence Pipeline (pretrain)
+
+Running `npx monomind hooks pretrain` executes:
+1. **RETRIEVE** — Top-k memory injection with MMR diversity
+2. **JUDGE** — LLM-as-judge trajectory evaluation
+3. **DISTILL** — Extract strategy memories from trajectories
+4. **CONSOLIDATE** — Dedup, detect contradictions, prune old patterns
+
+Optionally adds:
+5. **EMBED** — Index documents with ONNX model
+6. **HYPERBOLIC** — Poincaré ball projection for hierarchy preservation
+
+## Model Routing Output (pre-task)
+
+`npx monomind hooks pre-task -d "your task"` outputs one of:
+- `[AGENT_BOOSTER_AVAILABLE]` — skip LLM entirely, use Agent Booster (< 1ms, $0)
+- `[TASK_MODEL_RECOMMENDATION] Use model="haiku|sonnet|opus"` — use that model in Task tool