monomind 1.16.6 → 1.16.7

package/packages/@monomind/cli/.claude/commands/hooks/overview.md

@@ -0,0 +1,117 @@
+---
+name: hooks:overview
+---
+
+# Hooks System Overview
+
+Self-learning hooks for intelligent workflow automation. Hooks connect Claude Code tool events to Monomind's pattern learning, agent routing, and session persistence.
+
+## How It Works
+
+Claude Code fires hook events (PreToolUse, PostToolUse, etc.) which trigger `npx monomind hooks <subcommand>` commands. The hooks system:
+
+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
+
+## CLI Subcommands
+
+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` | JS trajectory and pattern logging (stats, pattern-*, trajectory-*) |
+| `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
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^(Write|Edit|MultiEdit)$",
+        "hooks": [{
+          "type": "command",
+          "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"
+        }]
+      }
+    ]
+  }
+}
+```
+
+## 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

package/packages/@monomind/cli/.claude/commands/hooks/post-edit.md

@@ -0,0 +1,78 @@
+---
+name: hooks:post-edit
+---
+
+# hooks post-edit
+
+Record editing outcome for neural pattern learning.
+
+## Usage
+
+```bash
+npx monomind hooks post-edit [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--file` | `-f` | string | `unknown` | File path that was edited |
+| `--success` | `-s` | boolean | `true` | Whether the edit succeeded |
+| `--outcome` | `-o` | string | — | Outcome description |
+| `--metrics` | `-m` | string | — | Performance metrics, e.g. `"time:500ms,quality:0.95"` |
+| `--format` | — | string | — | Output format: `json` |
+
+## Examples
+
+```bash
+# Record successful edit
+npx monomind hooks post-edit --file src/utils.ts --success true
+
+# Record failed edit with reason
+npx monomind hooks post-edit -f src/api.ts --success false -o "Type error in return type"
+
+# With performance metrics
+npx monomind hooks post-edit -f src/auth.ts --success true -m "time:200ms,quality:0.9"
+
+# JSON output
+npx monomind hooks post-edit -f src/utils.ts --format json
+```
+
+## Output
+
+- **Learning updates** — patterns updated, confidence adjustments, new patterns discovered
+
+## Claude Code Integration
+
+Typically fired automatically via `settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "^(Write|Edit|MultiEdit)$",
+      "hooks": [{
+        "type": "command",
+        "command": "npx monomind hooks post-edit --file '${tool.params.file_path}' --success true"
+      }]
+    }]
+  }
+}
+```
+
+## MCP Tool
+
+```javascript
+mcp__monomind__hooks_post_edit({
+  filePath: "src/utils.ts",
+  success: true,
+  outcome: "Added error handling",
+  metrics: { time: 200, quality: 0.9 },
+  timestamp: Date.now()
+})
+```
+
+## See Also
+
+- `hooks pre-edit` — get context before editing
+- `hooks metrics` — view learning metrics

package/packages/@monomind/cli/.claude/commands/hooks/post-task.md

@@ -0,0 +1,62 @@
+---
+name: hooks:post-task
+---
+
+# hooks post-task
+
+Record task completion for neural pattern learning.
+
+## Usage
+
+```bash
+npx monomind hooks post-task [options]
+```
+
+## Options
+
+| Flag | Short | Type | Required | Description |
+|---|---|---|---|---|
+| `--task-id` | `-i` | string | no | Task identifier (auto-generated if omitted) |
+| `--success` | `-s` | boolean | no | Whether task succeeded (default: true) |
+| `--quality` | `-q` | number | no | Quality score 0–1 |
+| `--agent` | `-a` | string | no | Agent that executed the task |
+| `--format` | — | string | no | Output format: `json` |
+
+## Examples
+
+```bash
+# Record successful completion
+npx monomind hooks post-task -i task-123 --success true
+
+# Record failed task with quality score
+npx monomind hooks post-task -i task-456 --success false -q 0.3
+
+# Record with agent attribution
+npx monomind hooks post-task -i task-789 --success true -a coder -q 0.95
+
+# JSON output
+npx monomind hooks post-task -i task-123 --success true --format json
+```
+
+## Output
+
+- Patterns updated / new patterns discovered
+- Task duration
+- Trajectory ID (for intelligence system tracking)
+
+## MCP Tool
+
+```javascript
+mcp__monomind__hooks_post_task({
+  taskId: "task-123",
+  success: true,
+  quality: 0.95,
+  agent: "coder",
+  timestamp: Date.now()
+})
+```
+
+## See Also
+
+- `hooks pre-task` — register task start
+- `hooks metrics` — view learning metrics

package/packages/@monomind/cli/.claude/commands/hooks/pre-edit.md

@@ -0,0 +1,81 @@
+---
+name: hooks:pre-edit
+---
+
+# hooks pre-edit
+
+Get context and agent suggestions before editing a file.
+
+## Usage
+
+```bash
+npx monomind hooks pre-edit [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--file` | `-f` | string | `unknown` | File path to edit |
+| `--operation` | `-o` | string | `update` | Edit operation: `create`, `update`, `delete`, `refactor` |
+| `--context` | `-c` | string | — | Additional context about the edit |
+| `--format` | — | string | — | Output format: `json` |
+
+## Examples
+
+```bash
+# Get context before editing a file
+npx monomind hooks pre-edit --file src/auth/login.ts
+
+# With operation type
+npx monomind hooks pre-edit -f src/api.ts -o refactor
+
+# With additional context
+npx monomind hooks pre-edit -f src/auth.ts -o update -c "Adding JWT refresh logic"
+
+# JSON output for scripting
+npx monomind hooks pre-edit -f src/utils.ts --format json
+```
+
+## Output
+
+- **File context** — file type, exists/not-exists, operation
+- **Suggested agents** — which agent types are best for this file
+- **Related files** — files likely affected by the edit
+- **Learned patterns** — matching patterns from past edits with confidence scores
+- **Potential risks** — warnings about the edit
+
+## Claude Code Integration
+
+Typically fired automatically via `settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "^(Write|Edit|MultiEdit)$",
+      "hooks": [{
+        "type": "command",
+        "command": "npx monomind hooks pre-edit --file '${tool.params.file_path}'"
+      }]
+    }]
+  }
+}
+```
+
+## MCP Tool
+
+```javascript
+mcp__monomind__hooks_pre_edit({
+  filePath: "src/auth/login.ts",
+  operation: "update",
+  context: "Adding JWT refresh logic",
+  includePatterns: true,
+  includeRisks: true
+})
+```
+
+## See Also
+
+- `hooks post-edit` — record edit outcome
+- `hooks route` — manual agent routing

package/packages/@monomind/cli/.claude/commands/hooks/pre-task.md

@@ -0,0 +1,76 @@
+---
+name: hooks:pre-task
+---
+
+# hooks pre-task
+
+Register task start, get agent suggestions, and receive model routing recommendations.
+
+## Usage
+
+```bash
+npx monomind hooks pre-task [options]
+```
+
+## Options
+
+| Flag | Short | Type | Required | Description |
+|---|---|---|---|---|
+| `--description` | `-d` | string | yes | Task description |
+| `--task-id` | `-i` | string | no | Unique task ID (auto-generated if omitted) |
+| `--auto-spawn` | `-a` | boolean | no | Auto-spawn suggested agents (default: false) |
+| `--format` | — | string | no | Output format: `json` |
+
+## Examples
+
+```bash
+# Register task start and get suggestions
+npx monomind hooks pre-task -d "Implement user authentication"
+
+# With explicit task ID
+npx monomind hooks pre-task -i task-123 -d "Fix auth bug"
+
+# With auto-spawn of suggested agents
+npx monomind hooks pre-task -d "Implement feature" --auto-spawn
+
+# JSON output for scripting
+npx monomind hooks pre-task -d "Refactor database layer" --format json
+```
+
+## Output
+
+The command outputs:
+- **Task registration** — task ID, complexity estimate, estimated duration
+- **Suggested agents** — agent type, confidence, reason
+- **Potential risks** — issues to watch for
+- **Recommendations** — approach suggestions
+- **Model routing** — one of:
+  - `[AGENT_BOOSTER_AVAILABLE]` — skip LLM, use Agent Booster (< 1ms, $0)
+  - `[TASK_MODEL_RECOMMENDATION] Use model="haiku|sonnet|opus"` — use that model
+
+## Integration in Claude Code
+
+Run before starting any significant task:
+
+```bash
+npx monomind hooks pre-task -d "Your task description here"
+```
+
+Then use the model routing output to set the Task tool's `model` parameter.
+
+## MCP Tool
+
+```javascript
+mcp__monomind__hooks_pre_task({
+  taskId: "task-123",
+  description: "Implement authentication",
+  autoSpawn: false,
+  timestamp: Date.now()
+})
+```
+
+## See Also
+
+- `hooks post-task` — record task completion
+- `hooks route` — manual agent routing
+- `hooks explain` — explain routing decision

package/packages/@monomind/cli/.claude/commands/hooks/session-end.md

@@ -0,0 +1,82 @@
+---
+name: hooks:session-end
+---
+
+# hooks session-end
+
+End the current session and persist state for later restoration.
+
+## Usage
+
+```bash
+npx monomind hooks session-end [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--save-state` | `-s` | boolean | `true` | Save session state for restoration |
+| `--format` | — | string | — | Output format: `json` |
+
+## Examples
+
+```bash
+# End and save session (default)
+npx monomind hooks session-end
+
+# End without saving state
+npx monomind hooks session-end --save-state false
+
+# JSON output
+npx monomind hooks session-end --format json
+```
+
+## Output
+
+Session summary including:
+- Session ID and duration
+- Tasks executed / succeeded / failed
+- Commands executed, files modified, agents spawned
+- State file path (if saved)
+
+## Restore Later
+
+```bash
+# Restore most recent session
+npx monomind hooks session-restore
+
+# Restore specific session
+npx monomind hooks session-restore -i session-12345
+```
+
+## Claude Code Integration
+
+Typically wired to run at conversation end:
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "npx monomind hooks session-end"
+      }]
+    }]
+  }
+}
+```
+
+## MCP Tool
+
+```javascript
+mcp__monomind__hooks_session_end({
+  saveState: true,
+  timestamp: Date.now()
+})
+```
+
+## See Also
+
+- `hooks session-restore` — restore a previous session
+- `hooks pre-task` / `hooks post-task` — task tracking within a session

package/packages/@monomind/cli/.claude/commands/hooks/setup.md

@@ -0,0 +1,132 @@
+---
+name: hooks:setup
+---
+
+# Setting Up Monomind Hooks
+
+## Quick Start
+
+### 1. Initialize with Hooks
+
+```bash
+npx monomind init --hooks
+```
+
+This automatically creates `.claude/settings.json` with hook configurations.
+
+### 2. Test Hook Functionality
+
+```bash
+# Test pre-edit hook
+npx monomind hooks pre-edit --file src/utils.ts
+
+# Test pre-task hook
+npx monomind hooks pre-task -d "Implement user authentication"
+
+# Test route
+npx monomind hooks route -t "Fix authentication bug"
+```
+
+### 3. Customize Hooks
+
+Edit `.claude/settings.json` to configure which hooks fire on which Claude Code events:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^(Write|Edit|MultiEdit)$",
+        "hooks": [{
+          "type": "command",
+          "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"
+        }]
+      },
+      {
+        "matcher": "^Bash$",
+        "hooks": [{
+          "type": "command",
+          "command": "npx monomind hooks post-command --command '${tool.params.command}' --success true"
+        }]
+      }
+    ]
+  }
+}
+```
+
+## Common Patterns
+
+### Task Tracking (manual)
+
+```bash
+# Record task start
+npx monomind hooks pre-task -d "Implement auth module"
+
+# After completing work, record result
+npx monomind hooks post-task -i task-123 --success true
+```
+
+### Route Before Spawning
+
+```bash
+# Get agent recommendation for a task
+npx monomind hooks route -t "Optimize database queries"
+
+# Understand why an agent was chosen
+npx monomind hooks explain -t "Fix authentication bug"
+```
+
+### Bootstrap from Repository
+
+```bash
+# Pretrain on current repo (medium depth + embeddings)
+npx monomind hooks pretrain
+
+# Deep analysis only, no embeddings
+npx monomind hooks pretrain --depth deep --no-with-embeddings
+
+# Generate optimized agent configs from pretrain data
+npx monomind hooks build-agents
+```
+
+### Session Persistence
+
+```bash
+# At session end
+npx monomind hooks session-end
+
+# At session start (restores latest)
+npx monomind hooks session-restore
+```
+
+## Debugging
+
+```bash
+# Enable debug output
+export MONOMIND_LOG_LEVEL=debug
+
+# List all registered hooks
+npx monomind hooks list
+
+# View learning metrics
+npx monomind hooks metrics
+
+# Check background workers
+npx monomind hooks worker list
+```