monomind 1.16.5 → 1.16.7

package/packages/@monomind/cli/.claude/commands/hive-mind/README.md

@@ -0,0 +1,42 @@
+---
+name: hive-mind:README
+---
+
+# Hive-Mind Commands
+
+Queen-led consensus-based multi-agent coordination system. All operations use the `mcp__monomind__hive-mind_*` MCP tools.
+
+## Commands (invoke as slash commands)
+
+- [hive-mind](./hive-mind.md) — overview of all subcommands, topologies, and quick start
+- [hive-mind-init](./hive-mind-init.md) — initialize hive with topology and consensus settings
+- [hive-mind-spawn](./hive-mind-spawn.md) — spawn workers; `--claude` launches Claude Code as Queen
+- [hive-mind-status](./hive-mind-status.md) — show hive status, workers, and metrics
+- [hive-mind-stop](./hive-mind-stop.md) — shutdown the hive (the `shutdown` subcommand)
+- [hive-mind-consensus](./hive-mind-consensus.md) — manage proposals and voting
+- [hive-mind-memory](./hive-mind-memory.md) — access hive shared memory
+
+## Real Subcommands (11 total)
+
+```
+init           Initialize hive with topology and consensus
+spawn          Spawn workers; --claude launches Claude Code as Queen
+status         Show status, workers, and metrics
+task           Submit a task for distributed execution
+join           Add an 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 hive shared memory
+optimize-memory Optimize memory patterns and consolidation
+shutdown       Gracefully shutdown the hive
+```
+
+## Real Tools Used
+
+- `mcp__monomind__hive-mind_init` / `hive-mind_spawn` / `hive-mind_status` — lifecycle
+- `mcp__monomind__hive-mind_task` / `hive-mind_join` / `hive-mind_leave` — task and agent management
+- `mcp__monomind__hive-mind_consensus` / `hive-mind_broadcast` — coordination
+- `mcp__monomind__hive-mind_memory` / `hive-mind_optimize-memory` / `hive-mind_shutdown` — memory and shutdown
+- `mcp__monomind__coordination_orchestrate` — cross-agent task distribution
+- `mcp__monomind__memory_store` / `memory_retrieve` — global persistent memory

package/packages/@monomind/cli/.claude/commands/hive-mind/hive-mind-consensus.md

@@ -0,0 +1,72 @@
+---
+name: hive-mind:hive-mind-consensus
+---
+
+# hive-mind consensus
+
+Manage consensus proposals and voting within the hive.
+
+## Usage
+```bash
+npx monomind hive-mind consensus [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--action` | `-a` | string | `list` | Action: `propose`, `vote`, `status`, `list` |
+| `--proposal-id` | `-p` | string | — | Proposal ID (required for `vote` and `status`) |
+| `--type` | `-t` | string | — | Proposal type (used with `propose`) |
+| `--value` | — | string | — | Proposal value (used with `propose`) |
+| `--vote` | `-v` | string | — | Vote to cast: `yes` or `no` (used with `vote`) |
+| `--voter-id` | — | string | — | Voter agent ID (used with `vote`) |
+| `--format` | — | string | — | Output format: `json` |
+
+## Examples
+
+```bash
+# List all pending proposals
+npx monomind hive-mind consensus
+
+# Create a new proposal
+npx monomind hive-mind consensus -a propose -t config-change --value '{"maxAgents":20}'
+
+# Vote on a proposal
+npx monomind hive-mind consensus -a vote -p proposal-abc123 -v yes --voter-id agent-1
+
+# Check proposal status
+npx monomind hive-mind consensus -a status -p proposal-abc123
+
+# List pending proposals as JSON
+npx monomind hive-mind consensus -a list --format json
+```
+
+## Actions
+
+- **`list`** — Show all pending proposals (default)
+- **`propose`** — Create a new consensus proposal (requires `--type` and `--value`)
+- **`vote`** — Cast a vote on a proposal (requires `--proposal-id`, `--vote`, and `--voter-id`)
+- **`status`** — Check the current vote tally for a proposal (requires `--proposal-id`)
+
+## MCP Tool
+
+```javascript
+// List proposals
+mcp__monomind__hive-mind_consensus({ action: "list" })
+
+// Create proposal
+mcp__monomind__hive-mind_consensus({
+  action: "propose",
+  type: "config-change",
+  value: '{"maxAgents":20}'
+})
+
+// Vote
+mcp__monomind__hive-mind_consensus({
+  action: "vote",
+  proposalId: "proposal-abc123",
+  vote: true,
+  voterId: "agent-1"
+})
+```

package/packages/@monomind/cli/.claude/commands/hive-mind/hive-mind-init.md

@@ -0,0 +1,68 @@
+---
+name: hive-mind:hive-mind-init
+---
+
+# hive-mind init
+
+Initialize a hive mind with topology and consensus settings.
+
+## Usage
+```bash
+npx monomind hive-mind init [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--topology` | `-t` | string | `hierarchical-mesh` | Hive topology: `hierarchical`, `mesh`, `hierarchical-mesh`, `adaptive` |
+| `--consensus` | `-c` | string | `byzantine` | Consensus strategy: `byzantine`, `raft`, `gossip`, `crdt`, `quorum` |
+| `--max-agents` | `-m` | number | `15` | Maximum number of agents |
+| `--persist` | `-p` | boolean | `true` | Enable persistent state across sessions |
+| `--memory-backend` | — | string | `hybrid` | Memory backend: `lancedb`, `sqlite`, `hybrid` |
+
+## Examples
+
+```bash
+# Initialize with recommended settings (interactive topology/consensus selection)
+npx monomind hive-mind init
+
+# Initialize hierarchical-mesh with Byzantine consensus
+npx monomind hive-mind init -t hierarchical-mesh -c byzantine
+
+# Large hive with 20 agents and CRDT consensus
+npx monomind hive-mind init -t mesh -c crdt -m 20
+
+# Minimal hive with no persistence
+npx monomind hive-mind init -t hierarchical -c raft --persist false
+
+# Output as JSON
+npx monomind hive-mind init -t hierarchical-mesh --format json
+```
+
+## Topology Guide
+
+- **`hierarchical`** — Queen controls workers directly. Best for small teams (< 8 agents). Prevents drift.
+- **`mesh`** — Fully connected peers. Best when all agents are equals.
+- **`hierarchical-mesh`** — Queen + peer communication. Recommended for 10+ agents. Most resilient.
+- **`adaptive`** — Dynamically adjusts topology based on current load and task type.
+
+## Consensus Guide
+
+- **`byzantine`** — Tolerates up to 1/3 faulty or malicious agents. Most robust. Default.
+- **`raft`** — Leader-based. Tolerates up to 1/2 failures. Faster than byzantine.
+- **`gossip`** — Epidemic propagation. Eventually consistent. Best for very large swarms.
+- **`crdt`** — Conflict-free. No coordination overhead. Best for parallel writes.
+- **`quorum`** — Simple majority. Configurable threshold.
+
+## MCP Tool
+
+```javascript
+mcp__monomind__hive-mind_init({
+  topology: "hierarchical-mesh",
+  consensus: "byzantine",
+  maxAgents: 15,
+  persist: true,
+  memoryBackend: "hybrid"
+})
+```

package/packages/@monomind/cli/.claude/commands/hive-mind/hive-mind-memory.md

@@ -0,0 +1,73 @@
+---
+name: hive-mind:hive-mind-memory
+---
+
+# hive-mind memory
+
+Access and manage hive shared memory — key-value store accessible to all agents in the hive.
+
+## Usage
+```bash
+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 LanceDB.
+
+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/packages/@monomind/cli/.claude/commands/hive-mind/hive-mind-spawn.md

@@ -0,0 +1,82 @@
+---
+name: hive-mind:hive-mind-spawn
+---
+
+# hive-mind spawn
+
+Spawn worker agents into the hive, or launch Claude Code as the Queen coordinator.
+
+## Usage
+```bash
+npx monomind hive-mind spawn [options]
+```
+
+## Options
+
+| 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
+# 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/packages/@monomind/cli/.claude/commands/hive-mind/hive-mind-status.md

@@ -0,0 +1,56 @@
+---
+name: hive-mind:hive-mind-status
+---
+
+# 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
+
+```bash
+# 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/packages/@monomind/cli/.claude/commands/hive-mind/hive-mind-stop.md

@@ -0,0 +1,55 @@
+---
+name: hive-mind:hive-mind-stop
+---
+
+# hive-mind shutdown
+
+Gracefully shutdown the hive mind, terminating all agents.
+
+## Usage
+```bash
+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/packages/@monomind/cli/.claude/commands/hive-mind/hive-mind.md

@@ -0,0 +1,87 @@
+---
+name: hive-mind:hive-mind
+---
+
+# hive-mind
+
+Queen-led consensus-based multi-agent coordination system.
+
+## Usage
+```bash
+npx monomind hive-mind <subcommand> [options]
+```
+
+## Subcommands
+
+| 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
+# 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
+
+# 3. (Optional) Launch Claude Code as the Queen coordinator
+npx monomind hive-mind spawn --claude -o "Build a REST API with auth"
+
+# 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/packages/@monomind/cli/.claude/commands/hooks/README.md

@@ -0,0 +1,66 @@
+---
+name: hooks:README
+---
+
+# Hooks Commands
+
+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      JS pattern/trajectory logging (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
+```
+
+## Real MCP Tools
+
+- `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.