monomind 1.10.47 → 1.10.55

package/.claude/commands/mastermind/understand.md

@@ -0,0 +1,139 @@
+---
+name: mastermind:understand
+description: "Monomind — Run semantic enrichment on the current project's monograph knowledge graph. Uses the active Claude Code session for LLM work — no API key needed."
+---
+
+# /mastermind:understand — Semantic Enrichment
+
+Enriches the current project's monograph knowledge graph with summaries, architectural
+layers, and semantic relationships.
+
+**Designed to run inside Claude Code** — uses YOUR current session for LLM work via
+the Task tool. No `ANTHROPIC_API_KEY` required. The script handles layer detection
+and DB writes; you (Claude) handle per-file summarization.
+
+## Parse Arguments
+
+Parse `$ARGUMENTS` for these flags:
+
+- `--dir <path>`      — project directory (default: cwd)
+- `--db <path>`       — monograph.db path (default: `<dir>/.monomind/monograph.db`)
+- `--full`            — force full re-analysis
+- `--no-llm`          — heuristic-only mode (no per-file summaries)
+- `--layers-only`     — skip per-file analysis, only re-detect layers
+- `--max-files <N>`   — stop after N files (0 = all)
+- `--dry-run`         — show what would happen, don't write
+
+Bare path argument → `--dir`.
+
+---
+
+## Step 1: Locate project, DB, and script
+
+```bash
+DIR="${ARGUMENTS_dir:-$(pwd)}"
+DB="${ARGUMENTS_db:-$DIR/.monomind/monograph.db}"
+
+# Find understand-analyze.mjs (ships with monomind globally)
+GLOBAL_ROOT=$(npm root -g 2>/dev/null)
+SCRIPT="$GLOBAL_ROOT/monomind/packages/@monomind/cli/scripts/understand-analyze.mjs"
+[ ! -f "$SCRIPT" ] && SCRIPT="$GLOBAL_ROOT/@monoes/monomindcli/scripts/understand-analyze.mjs"
+```
+
+If `$DB` does not exist:
+> monograph.db not found at `$DB`. Build it first: `npx monomind monograph build`
+
+If `$SCRIPT` does not exist:
+> understand engine missing. Update: `npm install -g monomind@latest`
+
+In either case, STOP.
+
+---
+
+## Step 2: Run the script in heuristic mode (always — fast and deterministic)
+
+This step is non-negotiable. The script handles:
+- File node discovery from monograph.db
+- Heuristic layer detection from file paths
+- DB writes (community_id + properties)
+- graph.json emission to `.understand/knowledge-graph.json`
+- Auto-shadowing the DB to `/tmp` when it lives on a network FS
+
+```bash
+node "$SCRIPT" --dir "$DIR" --db "$DB" --no-llm
+```
+
+Wait for completion. Capture stdout. Note how many file nodes were found and how
+many layers were detected. Do NOT advise the user about API keys.
+
+---
+
+## Step 3: Per-file summarization (ONLY if `--no-llm` and `--layers-only` are both UNSET)
+
+This is where YOU (the current Claude session) do the LLM work. The script left
+behind a fresh `.understand/knowledge-graph.json` with placeholder summaries.
+
+1. Read `.understand/knowledge-graph.json`. For each node where `properties.fileSummary`
+   is empty or marked `[heuristic]`, do the following:
+   - Use the `Read` tool on `node.file_path` (relative to `$DIR`).
+   - Produce a JSON object: `{ id, fileSummary, tags, complexity, functionSummaries, classSummaries }`
+     where:
+     - `fileSummary`: 1-2 sentences explaining what the file does
+     - `tags`: array of 2-5 short tags
+     - `complexity`: "simple" | "moderate" | "complex"
+     - `functionSummaries`: top-5 functions → 1-sentence each
+     - `classSummaries`: classes → 1-sentence each
+2. Process files in batches of 5 for efficiency. Use `--max-files` to cap if set.
+3. Collect all analyses into an `analyses` array.
+
+If `$ARGUMENTS` includes `--no-llm` or `--layers-only`, SKIP this step entirely.
+
+---
+
+## Step 4: Write analyses back to the DB
+
+Pipe the collected analyses to a small re-import:
+
+```bash
+echo "$ANALYSES_JSON" | node "$SCRIPT" --dir "$DIR" --db "$DB" --import-analyses-stdin
+```
+
+(If your `analyses` array is empty, skip this step.)
+
+---
+
+## Step 5: Report
+
+```
+╔══════════════════════════════════════════════════╗
+║  /mastermind:understand — Enrichment Done           ║
+╠══════════════════════════════════════════════════╣
+║  DB:              .monomind/monograph.db          ║
+║  Files analyzed:  <N>                             ║
+║  LLM summaries:   <N> (via active session)        ║
+║  Layers:          <N>                             ║
+║  graph.json:      .understand/knowledge-graph.json║
+╚══════════════════════════════════════════════════╝
+```
+
+If LLM summaries = 0 (because `--no-llm` was set), say "heuristic-only mode — no per-file summaries written".
+
+Then:
+> Open the Monomind control panel and click **Monograph → GRAPH** to see layers.
+> Each color = one architectural layer (API, Service, Data, UI, etc.).
+>
+> Follow-ups:
+> - `/mastermind:understand --full` — re-run from scratch
+> - `/mastermind:understand --layers-only` — refresh only layers
+> - `/mastermind:understand --no-llm` — heuristic-only mode
+
+---
+
+## Error Handling
+
+- Do NOT prompt the user to set `ANTHROPIC_API_KEY`. LLM work happens in this session.
+- 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 — report and return cleanly.
+
+To re-run on a schedule: wrap with `/mastermind:repeat`.

package/.claude/commands/mastermind/verify.md

@@ -0,0 +1,22 @@
+---
+name: mastermind-verify
+description: Run the verification gate before claiming any work is complete, fixed, or passing — evidence before assertions always.
+---
+
+**First — extract repeat flags:** Follow the REPEAT PREAMBLE from `_repeat.md`.
+
+Parse `$ARGUMENTS` for `--auto`, `--confirm`, `--project <name>`, and remaining text = claim_or_task.
+
+Load brain context for the `verify` domain (follow `_protocol.md` Brain Load Procedure).
+
+If claim_or_task is empty: ask "What claim or task needs verification?"
+
+Default mode: **auto**.
+
+---
+
+Invoke `Skill("mastermind:verify")` passing: brain_context, claim_or_task, project_name, mode.
+
+After skill returns: follow `_protocol.md` Brain Write Procedure for domain `verify`.
+
+Invoke `Skill("mastermind:_repeat")` now to execute the REPEAT POSTAMBLE. This is a required tool call — do not skip it.

package/.claude/commands/mastermind/worktree.md

@@ -0,0 +1,20 @@
+---
+name: mastermind-worktree
+description: Use when starting feature work that needs isolation from the current workspace or before executing implementation plans — sets up an isolated git worktree
+---
+
+**First — extract repeat flags:** Follow REPEAT PREAMBLE from `_repeat.md`.
+
+Parse `$ARGUMENTS` for `--auto`, `--confirm`, `--project <name>`, and remaining text.
+
+Load brain context (follow `_protocol.md` Brain Load Procedure).
+
+Default mode: **auto**.
+
+---
+
+Invoke `Skill("mastermind:worktree")` passing: brain_context, params, mode.
+
+After skill returns: follow `_protocol.md` Brain Write Procedure.
+
+Invoke `Skill("mastermind:_repeat")` now. Required — do not skip.

package/.claude/commands/monomind/do.md

@@ -196,6 +196,32 @@ All agents run concurrently via `run_in_background: true`.
 You have N tasks to execute in order. Complete each one before moving to the next.
 Tasks share context — knowledge from earlier tasks applies to later ones.
 
+== AGENT DELEGATION CAPABILITY ==
+You have full access to the Agent tool (Claude Code: Task tool) to spawn
+sub-agents for any specialized subtask. This capability is recursive —
+sub-agents you spawn also receive it.
+
+Available agent categories:
+  CORE      coder · reviewer · tester · planner · researcher
+  BACKEND   backend-dev · Backend Architect · DB Optimizer · API Tester
+  FRONTEND  Frontend Developer · mobile-dev · Mobile App Builder
+  ARCH      Software Architect · system-architect
+  SECURITY  Security Engineer · security-architect
+  AI/ML     AI Engineer · ml-developer · Data Engineer
+  DEVOPS    DevOps Automator · SRE · cicd-engineer
+  DOCS      Technical Writer · api-docs
+  PRODUCT   Product Manager · Launch Strategist · CRO Specialist
+  MARKETING Content Creator · SEO Specialist · Growth Hacker
+  SOCIAL    TikTok · LinkedIn · Twitter · Instagram Strategist
+  SALES     Deal Strategist · Sales Coach · Outbound Strategist
+  BUSINESS  Finance Tracker · Legal Compliance Checker · Analytics Reporter
+  DESIGN    Monodesign (UI/UX · brand · CSS · animation · design systems)
+
+Delegate when: a subtask needs deeper expertise, parallel work speeds things up,
+or a subtask is outside your domain but blocks your progress.
+How: Agent({ subagent_type: "slug", prompt: `full briefing + this delegation block`, run_in_background: true })
+=================================
+
 TASK 1 of N: <title>
 <full task context, checklist, acceptance criteria>
 
@@ -226,6 +252,32 @@ Report which task is blocked and list the remaining unstarted tasks.
 ```
 Execute this single task:
 
+== AGENT DELEGATION CAPABILITY ==
+You have full access to the Agent tool (Claude Code: Task tool) to spawn
+sub-agents for any specialized subtask. This capability is recursive —
+sub-agents you spawn also receive it.
+
+Available agent categories:
+  CORE      coder · reviewer · tester · planner · researcher
+  BACKEND   backend-dev · Backend Architect · DB Optimizer · API Tester
+  FRONTEND  Frontend Developer · mobile-dev · Mobile App Builder
+  ARCH      Software Architect · system-architect
+  SECURITY  Security Engineer · security-architect
+  AI/ML     AI Engineer · ml-developer · Data Engineer
+  DEVOPS    DevOps Automator · SRE · cicd-engineer
+  DOCS      Technical Writer · api-docs
+  PRODUCT   Product Manager · Launch Strategist · CRO Specialist
+  MARKETING Content Creator · SEO Specialist · Growth Hacker
+  SOCIAL    TikTok · LinkedIn · Twitter · Instagram Strategist
+  SALES     Deal Strategist · Sales Coach · Outbound Strategist
+  BUSINESS  Finance Tracker · Legal Compliance Checker · Analytics Reporter
+  DESIGN    Monodesign (UI/UX · brand · CSS · animation · design systems)
+
+Delegate when: a subtask needs deeper expertise, parallel work speeds things up,
+or a subtask is outside your domain but blocks your progress.
+How: Agent({ subagent_type: "slug", prompt: `full briefing + this delegation block`, run_in_background: true })
+=================================
+
 TASK: <title>
 <full task context, checklist, acceptance criteria>
 

package/.claude/commands/monomind/improve.md

@@ -61,6 +61,8 @@ Collect ALL of the following in parallel (skip any that error):
 
 Bundle all gathered information into a single `PROJECT_CONTEXT` string for downstream agents.
 
+**DELEGATION RULE:** Every agent spawned in this command MUST include the `== AGENT DELEGATION CAPABILITY ==` block (from `mastermind/_delegation.md`) in its prompt, immediately before `YOUR GOAL:`. This lets each agent spawn its own sub-agents when needed — delegation is recursive.
+
 ---
 
 ## Step 2: Deep Component Analysis

package/.claude/helpers/handlers/graph-status-handler.cjs

@@ -27,7 +27,8 @@ module.exports = {
                + (usage.graph_assist_search || 0) + (usage.graph_assist_neighbors || 0);
       var search = (usage.grep_call || 0) + (usage.glob_call || 0)
                  + (usage.bash_grep_call || 0) + (usage.bash_find_call || 0);
-      var pct = (wins + search) > 0 ? Math.round((wins / (wins + search)) * 100) : 0;
+      var total = wins + search + (usage.preresolve_miss || 0);
+      var pct = total > 0 ? Math.round((wins / total) * 100) : 0;
       var saved = usage.dollars_saved || 0;
       console.log('Monograph: ' + n.toLocaleString() + ' nodes · ' + e.toLocaleString() + ' edges');
       console.log('Usage: ' + pct + '% graph · ' + (100 - pct) + '% grep · ' +

package/.claude/helpers/handlers/route-handler.cjs

@@ -76,10 +76,13 @@ module.exports = {
         var resConf = (result.confidence != null ? result.confidence : 0);
         var resReason = String(result.reason || '');
         var fromKeywordStage = resReason.indexOf('Keyword 2-stage') !== -1;
-        var promptIsDevish = /\b(improve|refactor|fix|bug|optimi[sz]e|implement|build|debug|deploy|test|feature|system|performance|architecture|memory|hook|graph|statusline|monograph|api|cli|skill|hooks|agent|workflow|init|module|package|registry|server|client|route|handler)\b/i.test(prompt);
+        var promptIsDevish = /\b(develop(?:ment|er)?|routing|improve|refactor|fix|bug|optimi[sz]e|implement|build|debug|deploy|test|feature|system|performance|architecture|memory|hook|graph|statusline|monograph|api|cli|skill|hooks|agent|workflow|init|module|package|registry|server|client|route|handler|localhost|dashboard|sidebar|layout|component|function|class|config|port|script|parse|compile|lint|build)\b/i.test(prompt);
 
+        // Align with the 90% primary-panel threshold: any non-dev pick below
+        // 90% confidence gets overridden via the graph, unless the prompt
+        // explicitly uses non-dev domain language (nonDevPrompt guard).
         var shouldOverride = !nonDevPrompt && (
-          (!pickedDev && resConf < 0.85) ||
+          (!pickedDev && resConf < 0.90) ||
           (fromKeywordStage && promptIsDevish)
         );
         if (shouldOverride) {
@@ -117,33 +120,80 @@ module.exports = {
       var output = [];
       output.push('[INFO] Routing task: ' + (prompt.substring(0, 80) || '(no prompt)'));
       output.push('');
-      // Suppress the agent recommendation panel for low-confidence routes on
-      // short prompts — the recommendation is almost always wrong (e.g.
-      // "what else can we do" → marketing → China E-Commerce). Saves ~150
-      // tokens per prompt. Skill matches and specific agents still render
-      // below when confidence is decent.
+      // Routing panel strategy:
+      //   conf >= 0.90 → show primary recommendation (router is confident, trust it)
+      //   conf  < 0.90 → show category picker so Claude uses its own context to
+      //                   pick the right agent category + agent from a menu.
+      //                   Specific-agent panel is suppressed (category menu replaces it).
       var conf = result.confidence != null ? result.confidence : 0;
       var promptShort = (prompt || '').trim().length < 60;
       var lowConf = conf < 0.70;
       var suppressPanel = lowConf && promptShort;
-      if (!suppressPanel) {
+
+      // Agent category menu — shown when conf < 0.90 so Claude picks with context.
+      var AGENT_CATEGORIES = [
+        { label: 'CORE',      agents: 'coder · reviewer · tester · planner · researcher' },
+        { label: 'BACKEND',   agents: 'backend-dev · Backend Architect · DB Optimizer' },
+        { label: 'FRONTEND',  agents: 'Frontend Developer · mobile-dev' },
+        { label: 'ARCH',      agents: 'Software Architect · system-architect' },
+        { label: 'SECURITY',  agents: 'Security Engineer · security-architect' },
+        { label: 'AI/ML',     agents: 'AI Engineer · ml-developer · Data Engineer' },
+        { label: 'DEVOPS',    agents: 'DevOps Automator · SRE · cicd-engineer' },
+        { label: 'DOCS',      agents: 'Technical Writer · api-docs' },
+        { divider: 'Non-Coding Agents' },
+        { label: 'PRODUCT',   agents: 'Product Manager · Launch Strategist · CRO Spec.' },
+        { label: 'MARKETING', agents: 'Content Creator · SEO Specialist · Growth Hacker' },
+        { label: 'SOCIAL',    agents: 'TikTok · LinkedIn · Twitter · Instagram Strat.' },
+        { label: 'SALES',     agents: 'Deal Strategist · Sales Coach · Outbound Strat.' },
+        { label: 'BUSINESS',  agents: 'Finance Tracker · Legal Compliance · Analytics' },
+        { label: 'DESIGN',    agents: 'Monodesign (UI/UX · brand · CSS · animation)' },
+      ];
+
+      if (conf >= 0.90) {
         output.push('+------------- monomind | Primary Recommendation --------------+');
         output.push('| Agent: ' + (result.agent || 'unknown').substring(0, 54).padEnd(54) + '|');
         output.push('| Confidence: ' + ((result.confidence != null ? (result.confidence * 100).toFixed(1) : '?') + '%').padEnd(49) + '|');
         output.push('| Reason: ' + (result.reason || '').substring(0, 53).padEnd(53) + '|');
         output.push('+--------------------------------------------------------------+');
+      } else if (!suppressPanel) {
+        output.push('+------- monomind | Agent Category Picker ---------------------+');
+        output.push('| ' + ('Conf: ' + (conf * 100).toFixed(0) + '% — router uncertain. YOU choose using context.').padEnd(60) + ' |');
+        output.push('+--------------------------------------------------------------+');
+        AGENT_CATEGORIES.forEach(function(cat) {
+          if (cat.divider) {
+            var d = '- ' + cat.divider + ' ';
+            output.push('|' + d.padEnd(31, '-') + ''.padEnd(31, '-') + '|');
+          } else {
+            output.push('| ' + cat.label.padEnd(10) + cat.agents.substring(0, 50).padEnd(50) + ' |');
+          }
+        });
+        output.push('+--------------------------------------------------------------+');
+        output.push('| INSTRUCTION: Read your conversation context. Identify the    |');
+        output.push('| best-fit category above, then pick one agent from it and     |');
+        output.push('| spawn it via Task({ subagent_type: "name" }). If no agent    |');
+        output.push('| fits the task, skip and proceed directly. Do this now.       |');
+        output.push('+--------------------------------------------------------------+');
       }
 
       // ── Persist routing result for statusline display ─────────────
       try {
         var routeDir = path.join(CWD, '.monomind');
         fs.mkdirSync(routeDir, { recursive: true });
-        // Always use the resolved agent name — never persist "extras"
+        // When confidence < 90% and the router picked a non-dev agent without
+        // a graph override, don't persist the wrong specialist — show "AI" instead.
+        var confForPersist = result.confidence != null ? result.confidence : 0;
+        var devAgentsForPersist = /^(coder|tester|reviewer|planner|researcher|system-architect|backend-dev|backend-architect|mobile-dev|ml-developer|cicd-engineer|api-docs|code-analyzer|production-validator|Technical Writer|Software Architect|Frontend Developer|AI Engineer|Data Engineer|Security Engineer|DevOps Automator|SRE)$/i;
+        var persistedIsNonDev = !devAgentsForPersist.test(String(result.agent || '').trim());
         var resolvedAgent = result.agent;
         if (!resolvedAgent || resolvedAgent === 'extras') {
           var topExtra = result.extrasMatches && result.extrasMatches[0];
           resolvedAgent = topExtra ? topExtra.name : 'Specialist Agent';
         }
+        // If router was uncertain (< 90%) and picked a non-dev specialist,
+        // show "AI selecting" in statusline rather than the wrong agent.
+        if (confForPersist < 0.90 && persistedIsNonDev && !String(result.reason || '').startsWith('Graph fallback')) {
+          resolvedAgent = 'AI selecting';
+        }
         var routePayload = {
           agent: resolvedAgent,
           agentSlug: result.agentSlug || null,
@@ -213,7 +263,7 @@ module.exports = {
       // ── Specific agent panel ──────────────────────────────────────────────────
       // Skip entirely on suppressed (low-confidence + short) prompts.
       var specificAgents = result.specificAgents || [];
-      if (specificAgents.length > 0 && !suppressPanel) {
+      if (specificAgents.length > 0 && !suppressPanel && conf >= 0.90) {
         output.push('');
         var saHdr = '------- Specific Agents (' + specificAgents.length + ' available) ';
         output.push('+' + saHdr + '-'.repeat(Math.max(1, 62 - saHdr.length)) + '+');
@@ -232,7 +282,7 @@ module.exports = {
 
       // ── Specialist agents (non-dev domain) — only shown when specificAgents panel wasn't shown ──
       var extras = result.extrasMatches || [];
-      var specificAgentsShown = (result.specificAgents || []).length > 0;
+      var specificAgentsShown = (result.specificAgents || []).length > 0 && conf >= 0.90;
       if (extras.length > 0 && !specificAgentsShown && !suppressPanel) {
         output.push('');
         var spHdr = '------- Specialist Agents (' + extras.length + ' matched) ';

package/.claude/helpers/hook-handler.cjs

@@ -267,6 +267,25 @@ const handlers = {
     h.handle(hCtx);
   },
 
+  'pre-bash': () => {
+    // Record bash grep/find calls for graph-vs-grep telemetry
+    var cmd = (hCtx.toolInput && (hCtx.toolInput.command || hCtx.toolInput.cmd)) || '';
+    if (/\bgrep\b/.test(cmd)) _recordGraphTelemetry('bash_grep_call');
+    else if (/\bfind\b/.test(cmd)) _recordGraphTelemetry('bash_find_call');
+  },
+
+  'pre-search': () => {
+    // Record Grep/Glob tool calls for graph-vs-grep telemetry
+    var tool = hCtx.toolName || '';
+    if (tool === 'Grep') _recordGraphTelemetry('grep_call');
+    else if (tool === 'Glob') _recordGraphTelemetry('glob_call');
+  },
+
+  'post-graph-tool': () => {
+    // Record monograph MCP tool calls as graph wins
+    _recordGraphTelemetry('monograph_call');
+  },
+
   'graph-status': () => {
     const h = require('./handlers/graph-status-handler.cjs');
     h.handle(hCtx);