monomind 1.10.1 → 1.10.2

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

@@ -0,0 +1,191 @@
+---
+name: monomind:understand
+description: "Monomind — Run semantic enrichment on the current project's monograph knowledge graph. No external plugin needed — the analysis engine ships with monomind."
+---
+
+# /monomind:understand — Semantic Enrichment
+
+Enriches the current project's monograph knowledge graph with LLM-generated summaries,
+architectural layers, and semantic relationships.
+
+The analysis engine is built into monomind — no external plugin installation required.
+
+## 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 analysis, run ua-import.mjs)
+- `--graph <path>`    — explicit path to a graph.json to import (implies `--import`)
+- `--full`            — force full re-analysis even if graph.json is recent
+- `--no-llm`          — heuristic-only mode: detect layers from file paths, no API calls
+- `--layers-only`     — skip per-file analysis, only (re-)detect architectural layers
+- `--incremental`     — re-analyze only files changed since the last run (uses git diff)
+- `--onboard`         — generate an ONBOARDING.md guide from the enriched graph
+- `--onboard-out <path>` — where to write the onboarding guide (default: `<dir>/ONBOARDING.md`)
+- `--batch-size <N>`  — files per LLM batch (default: 5, increase for faster analysis)
+- `--max-files <N>`   — stop after N files (0 = all)
+- `--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: Locate the built-in analysis engine
+
+The `understand-analyze.mjs` script ships with `@monomind/cli`. Find it:
+
+```bash
+# Try npm root (global install / homebrew)
+GLOBAL_ROOT=$(npm root -g 2>/dev/null)
+SCRIPT="$GLOBAL_ROOT/@monomind/cli/scripts/understand-analyze.mjs"
+
+# If not found globally, try npx resolve
+if [ ! -f "$SCRIPT" ]; then
+  SCRIPT=$(node -e "try{console.log(require.resolve('@monomind/cli/scripts/understand-analyze.mjs'))}catch{}" 2>/dev/null)
+fi
+
+# Fallback: walk up from the running CLI's __dirname
+if [ ! -f "$SCRIPT" ]; then
+  SCRIPT=$(node -e "
+    const {createRequire} = require('module');
+    const r = createRequire(require.resolve('monomind'));
+    try { console.log(r.resolve('@monomind/cli/scripts/understand-analyze.mjs')); } catch {}
+  " 2>/dev/null)
+fi
+```
+
+If the script is still not found:
+> The built-in understand engine (understand-analyze.mjs) was not found.
+> Update monomind: `npm install -g monomind@latest`
+
+And STOP.
+
+---
+
+## Step 3: Check for existing graph.json (unless `--full`)
+
+Look for (in order):
+- `$DIR/.understand/knowledge-graph.json`
+- `$DIR/.understand/graph.json`
+- `$DIR/.ua/graph.json`
+
+If `--graph <path>` was supplied, use that path directly.
+
+**If a recent graph.json is found AND `--full` was NOT set:**
+
+Report the file age and jump to **Step 5: Import**:
+```
+Found graph.json (X hours old) — importing into monograph…
+```
+
+**If `--import` or `--graph` was set:**
+Jump directly to **Step 5: Import**.
+
+**Otherwise:**
+Proceed to **Step 4: Run analysis**.
+
+---
+
+## Step 4: Run built-in analysis
+
+Run the built-in engine. Build the command from parsed flags:
+
+```bash
+node "$SCRIPT" \
+  --dir "$DIR" \
+  --db "$DB" \
+  [--no-llm]           # if --no-llm was set
+  [--layers-only]      # if --layers-only was set
+  [--incremental]      # if --incremental was set
+  [--onboard]          # if --onboard was set
+  [--onboard-out PATH] # if --onboard-out was set
+  [--dry-run]          # if --dry-run was set
+  [--batch-size N]     # if --batch-size was set
+  [--max-files N]      # if --max-files was set
+```
+
+The script will:
+1. Read all file nodes from the monograph DB
+2. For each file, call the Anthropic API (via `ANTHROPIC_API_KEY`) to get summaries, tags, and complexity
+3. Detect architectural layers (LLM-based if API key available, heuristic fallback otherwise)
+4. Write enrichment data back to `monograph.db` (community_id + properties JSON)
+5. Emit a `graph.json` to `$DIR/.understand/knowledge-graph.json`
+
+If `ANTHROPIC_API_KEY` is not set, the script automatically falls back to `--no-llm` mode — heuristic layer detection from file paths, no per-file summaries. Tell the user this happened.
+
+Wait for the script to complete before proceeding.
+
+---
+
+## Step 5: Import (only when using an existing graph.json)
+
+If jumping here from Step 3 (existing graph.json found):
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+IMPORT_SCRIPT="$REPO_ROOT/scripts/ua-import.mjs"
+# fallback: alongside understand-analyze.mjs
+[ ! -f "$IMPORT_SCRIPT" ] && IMPORT_SCRIPT="$(dirname $SCRIPT)/../../../scripts/ua-import.mjs"
+node "$IMPORT_SCRIPT" "$GRAPH_JSON" "$DB"
+```
+
+If `--dry-run` was set, report what would be imported without writing to the DB.
+
+---
+
+## Step 6: Report results
+
+After the analysis or import completes, show a summary:
+
+```
+╔══════════════════════════════════════════════════╗
+║  /monomind:understand — Enrichment Done           ║
+╠══════════════════════════════════════════════════╣
+║  DB:              .monomind/monograph.db          ║
+║  Nodes enriched:  <N>                             ║
+║  Communities:     <N> (layers detected)           ║
+║  graph.json:      .understand/knowledge-graph.json║
+╚══════════════════════════════════════════════════╝
+```
+
+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 represents an architectural layer (API, Service, Data, UI, etc.).
+>
+> To re-run with full LLM analysis: `/monomind:understand --full`
+> To only refresh layer detection: `/monomind:understand --layers-only`
+> To run without API calls: `/monomind:understand --no-llm`
+> To re-analyze only changed files: `/monomind:understand --incremental`
+> To generate an onboarding guide: `/monomind:understand --onboard`
+
+---
+
+## Error Handling
+
+- If `ANTHROPIC_API_KEY` is not set, automatically use heuristic mode — report this clearly but do NOT stop.
+- If the script exits non-zero, show stderr and suggest `npm install -g monomind@latest`.
+- If monograph.db has no file nodes, tell the user to run `npx monomind monograph build` first.
+- All errors are non-fatal to the main session — report and return cleanly.
+
+To repeat this command on a schedule, wrap it with `/monomind:repeat`.

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

@@ -0,0 +1,73 @@
+---
+name: optimization:README
+description: Optimization skills index — swarm topology selection, parallel execution patterns, and system-level performance tuning
+---
+
+# Optimization Commands
+
+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 |
+
+## See Also
+
+- `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

@@ -0,0 +1,85 @@
+---
+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
+---
+
+# Auto Topology Selection
+
+Automatically select the optimal swarm topology based on task complexity so you don't have to configure it manually.
+
+## How It Works
+
+### 1. Get a Routing Recommendation
+
+Before spawning agents, run the `pre-task` hook. It analyzes task complexity and recommends a topology:
+
+```bash
+npx monomind hooks pre-task -d "Refactor authentication system with JWT, add tests, update docs"
+```
+
+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
+```
+
+### 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
+})
+```
+
+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
+```
+
+## Hook Integration
+
+`pre-task` fires automatically if wired in `settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "^Task$",
+      "hooks": [{
+        "type": "command",
+        "command": "npx monomind hooks pre-task -d '${tool.params.description}'"
+      }]
+    }]
+  }
+}
+```
+
+## See Also
+
+- `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

@@ -0,0 +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
+
+Execute independent subtasks in parallel for maximum throughput. Parallel execution is handled by Claude Code's Task tool — not a CLI command.
+
+## The Pattern: Spawn All Agents in One Message
+
+```javascript
+// Initialize swarm coordination
+// npx monomind swarm init --topology hierarchical --max-agents 8 --strategy specialized
+
+// 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 });
+```
+
+After spawning, **stop and wait** — do not poll or check status. Agents report back when done.
+
+## Coordination via MCP
+
+```javascript
+// Orchestrate a parallel task plan
+mcp__monomind__coordination_orchestrate({
+  task: "Build REST API with auth, CRUD, and tests",
+  strategy: "parallel",
+  maxAgents: 8
+})
+```
+
+## 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 })
+```
+
+## See Also
+
+- `swarm init` — configure topology before spawning
+- `status` — monitor parallel execution progress
+- `hooks pre-task` — get agent recommendations before spawning

package/.claude/commands/optimization/performance-optimize.md

@@ -0,0 +1,79 @@
+---
+name: optimization:performance-optimize
+description: Analyze and apply system-level performance optimizations — memory, CPU, and latency using npx monomind performance optimize
+---
+
+# performance optimize
+
+Analyze and apply system-level performance optimizations — memory, CPU, and latency.
+
+## Usage
+
+```bash
+npx monomind performance optimize [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--target` | `-t` | string | `all` | Optimization target: `memory`, `cpu`, `latency`, `all` |
+| `--apply` | `-a` | boolean | `false` | Apply recommended optimizations |
+| `--dry-run` | `-d` | boolean | `false` | Show recommended changes without applying |
+
+## Examples
+
+```bash
+# Analyze and show recommendations (no changes)
+npx monomind performance optimize --dry-run
+
+# Optimize everything and apply
+npx monomind performance optimize --target all --apply
+
+# Memory-specific optimization
+npx monomind performance optimize --target memory --apply
+
+# CPU optimization only
+npx monomind performance optimize --target cpu --apply
+
+# Latency optimization (MCP response time)
+npx monomind performance optimize --target latency --apply
+```
+
+## Optimization Targets
+
+| Target | What It Optimizes |
+|---|---|
+| `memory` | Memory backend compression, HNSW rebuild, cache eviction |
+| `cpu` | Agent pool sizing, task batching, concurrency limits |
+| `latency` | MCP response caching, neural model quantization |
+| `all` | All of the above |
+
+## Related Commands
+
+```bash
+# Find bottlenecks before optimizing
+npx monomind performance bottleneck
+
+# Run benchmarks to measure before/after
+npx monomind performance benchmark --suite all
+
+# View current performance metrics
+npx monomind performance metrics
+```
+
+## MCP Tool
+
+```javascript
+mcp__monomind__performance_optimize({
+  target: "all",
+  apply: false
+})
+```
+
+## See Also
+
+- `performance bottleneck` — diagnose what to optimize first
+- `performance benchmark` — measure optimization impact
+- `performance metrics` — track performance over time
+- `neural optimize` — optimize neural model weights

package/.claude/commands/pair/README.md

@@ -0,0 +1,79 @@
+---
+name: pair:README
+description: Pair programming with Claude Code — driver/navigator modes, TDD sessions, review sessions, Task tool agent spawning, and hooks integration
+---
+
+# Pair Programming with Claude Code
+
+Collaborative development using Claude Code as your AI pair partner. No special CLI needed — Claude Code IS the pair partner.
+
+## How It Works
+
+Pair programming with Claude Code means structuring your conversation to get the most out of the collaboration. Depending on your goal, you drive or Claude drives.
+
+## Quick Start
+
+**You drive, Claude reviews (driver mode):**
+> "I'm going to implement JWT auth. Review my approach and flag issues as we go."
+
+**Claude drives, you guide (navigator mode):**
+> "Implement a JWT auth middleware for Express with refresh token support. I'll review each piece."
+
+**TDD session:**
+> "Let's do TDD for this shopping cart feature. Write the failing tests first, then we'll implement."
+
+**Review session:**
+> "Review all the changes I've made today to `src/auth/`. Focus on security issues."
+
+## Using the Pair Programming Skill
+
+Invoke the `pair-programming` skill for structured collaboration:
+
+```
+/pair-programming
+```
+
+This loads the workflow guide and sets up the session context.
+
+## Spawning a Specialized Agent
+
+For long-running or complex sessions, spawn a dedicated coding agent via the Task tool:
+
+```javascript
+Task({
+  prompt: "Act as a senior developer pair programming partner. The user is implementing JWT auth. Review their code as they write it, suggest improvements, catch issues, and explain patterns. Start by asking what they want to build.",
+  subagent_type: "Senior Developer",
+  run_in_background: false
+})
+```
+
+Or use a specific specialist:
+- `superpowers:test-driven-development` — TDD-focused pairing
+- `superpowers:systematic-debugging` — debugging sessions
+- `superpowers:receiving-code-review` — code review sessions
+
+## Hooks Integration
+
+Use hooks to track pair session quality:
+
+```bash
+# Register session start
+npx monomind hooks pre-task -d "Pair programming: implement JWT auth"
+
+# After session, record outcome
+npx monomind hooks post-task --task-id <id> --success true --quality 0.95
+```
+
+## Files
+
+- [modes.md](./modes.md) — Driver, navigator, TDD, review, debug modes
+- [session.md](./session.md) — Session lifecycle and real monitoring commands
+- [examples.md](./examples.md) — Real-world pair programming scenarios
+
+## See Also
+
+- `superpowers:pair-programming` — structured pair programming skill
+- `superpowers:test-driven-development` — TDD workflow
+- `superpowers:systematic-debugging` — debugging workflow
+- `superpowers:requesting-code-review` — code review workflow
+- `hooks pre-task` — register task start and get recommendations