@monoes/cli 1.0.9 → 1.2.0

package/.claude/agents/analysis/graphify/graphify-analyst.md

@@ -0,0 +1,145 @@
+---
+name: graphify-analyst
+description: "Knowledge graph analyst for codebase architecture and project understanding. Uses graphify's persistent knowledge graph to answer structural questions without reading files — reveals god nodes, community clusters, dependency paths, and cross-component surprises."
+type: graphify-analyst
+color: violet
+priority: high
+triggers:
+  - "understand the codebase"
+  - "how does * work"
+  - "what calls *"
+  - "architecture overview"
+  - "dependency between"
+  - "project structure"
+  - "how is * related to"
+  - "explain the flow"
+  - "what depends on"
+metadata:
+  specialization: "Knowledge graph-based codebase analysis"
+  requires: "graphify Python package (pip install graphifyy[mcp])"
+  capabilities:
+    - Zero-file-read architecture understanding via knowledge graph
+    - God node identification (most connected core abstractions)
+    - Community/subsystem detection and analysis
+    - Shortest dependency path between any two components
+    - Cross-community surprising connection detection
+    - Code vs documentation relationship mapping
+    - Confidence-aware edge reasoning (EXTRACTED/INFERRED/AMBIGUOUS)
+---
+
+# Graphify Analyst Agent
+
+A specialist in codebase understanding through knowledge graphs. Instead of reading files, this agent queries a persistent, pre-built graph of your entire project — delivering architectural insights in seconds.
+
+## When to Use This Agent
+
+Use graphify-analyst **instead of reading files** when you need to:
+- Understand how components relate to each other
+- Find the core abstractions of an unfamiliar codebase
+- Trace a dependency chain from A to B
+- Identify which subsystems exist and what belongs to each
+- Detect unexpected coupling between modules
+- Answer "what is the most important class/function/concept here?"
+
+## Workflow
+
+### Step 1 — Check graph exists
+```
+mcp__monobrain__graphify_stats
+```
+If no graph: tell user to run `python -m graphify <project-path>` first.
+
+### Step 2 — Get orientation (always start here)
+```
+mcp__monobrain__graphify_god_nodes { topN: 15 }
+```
+The top god nodes ARE the architecture. Everything important will be connected to them.
+
+### Step 3 — Query by concept
+```
+mcp__monobrain__graphify_query { question: "authentication", mode: "bfs", depth: 3 }
+```
+Match the question to the user's actual concern. Use `dfs` to trace a specific call path.
+
+### Step 4 — Understand subsystems
+```
+mcp__monobrain__graphify_community { communityId: 0 }  // largest cluster
+```
+Each community is a logical subsystem. Review all communities to understand module boundaries.
+
+### Step 5 — Trace specific dependencies
+```
+mcp__monobrain__graphify_shortest_path { source: "Router", target: "Database" }
+```
+Use to answer "how does X reach Y?" — reveals hidden coupling chains.
+
+### Step 6 — Find surprises
+```
+mcp__monobrain__graphify_surprises { topN: 10 }
+```
+Cross-community connections often reveal design smells or important but non-obvious integrations.
+
+## Output Format
+
+Always structure your response as:
+
+```
+## Architecture Overview
+[Top god nodes — the core abstractions]
+
+## Subsystems / Communities
+[What each community represents]
+
+## Key Relationships
+[Most important edges and what they mean]
+
+## Surprising Connections
+[Cross-community edges worth noting]
+
+## Confidence Notes
+[Which edges are EXTRACTED vs INFERRED vs AMBIGUOUS]
+
+## Recommendations
+[Architectural observations, potential improvements]
+```
+
+## Confidence Interpretation
+
+| Confidence | Meaning | Trust Level |
+|---|---|---|
+| EXTRACTED | Explicitly in source (import, call, inheritance) | High — treat as fact |
+| INFERRED | Reasonable deduction with confidence score | Medium — verify if critical |
+| AMBIGUOUS | Uncertain — flagged for review | Low — use as hypothesis only |
+
+## Building the Graph
+
+If `graphify_stats` shows no graph:
+
+```bash
+# Install
+pip install graphifyy[mcp]
+
+# Build graph for current project
+python -m graphify .
+
+# Query via MCP (starts stdio server)
+python -m graphify.serve graphify-out/graph.json --mcp
+
+# Or rebuild only code changes (fast, no LLM)
+python -m graphify --update .
+```
+
+## Limits
+
+- Graph must be built before querying — it does not auto-build
+- Very large codebases (500k+ LOC) may have slow initial builds
+- Doc/paper semantic edges require LLM — code AST edges are free
+- Graph reflects state at build time — use `graphify_build { codeOnly: true }` to refresh after code changes
+
+## Integration with Other Agents
+
+After graphify-analyst provides architectural context, hand off to:
+- **coder** — for implementation using the architectural understanding
+- **reviewer** — for code review informed by community/dependency context  
+- **architect** — for refactoring suggestions based on surprising connections
+- **security-auditor** — for security review focusing on EXTRACTED cross-boundary edges

package/dist/src/commands/init.js

@@ -655,6 +655,7 @@ const skillsCommand = {
                 mcp: false,
                 runtime: false,
                 claudeMd: false,
+                graphify: false,
             },
             skills: {
                 all: ctx.flags.all,
@@ -706,6 +707,7 @@ const hooksCommand = {
                 mcp: false,
                 runtime: false,
                 claudeMd: false,
+                graphify: false,
             },
             hooks: minimal
                 ? {

package/dist/src/init/executor.js

@@ -283,6 +283,10 @@ export async function executeInit(options) {
         }
         // Count enabled hooks
         result.summary.hooksEnabled = countEnabledHooks(options);
+        // Build knowledge graph in background (non-blocking)
+        if (options.components.graphify) {
+            await initKnowledgeGraph(targetDir, result);
+        }
     }
     catch (error) {
         result.success = false;
@@ -290,6 +294,38 @@ export async function executeInit(options) {
     }
     return result;
 }
+/**
+ * Spawn a background process to build the @monobrain/graph knowledge graph.
+ * Fire-and-forget: init does not wait for the graph build to complete.
+ * Non-fatal: if @monobrain/graph is unavailable the step is simply skipped.
+ */
+async function initKnowledgeGraph(targetDir, result) {
+    try {
+        await import('@monoes/graph');
+        const outputDir = path.join(targetDir, '.monobrain', 'graph');
+        const { spawn } = await import('child_process');
+        const safePath = targetDir.replace(/'/g, "\\'");
+        const safeOut = outputDir.replace(/'/g, "\\'");
+        const script = `
+import('@monoes/graph').then(({ buildGraph }) =>
+  buildGraph('${safePath}', { codeOnly: true, outputDir: '${safeOut}' })
+).then(r => console.log('[graph] built: ' + r.analysis.stats.nodes + ' nodes'))
+ .catch(e => console.error('[graph] build failed:', e.message));
+`;
+        const child = spawn(process.execPath, ['--input-type=module'], {
+            stdio: ['pipe', 'ignore', 'ignore'],
+            detached: true,
+            cwd: targetDir,
+        });
+        child.stdin?.write(script);
+        child.stdin?.end();
+        child.unref();
+        result.created.files.push('.monobrain/graph/ (knowledge graph building in background)');
+    }
+    catch (_err) {
+        result.skipped.push('knowledge graph: @monobrain/graph not available');
+    }
+}
 /**
  * Merge new settings into existing settings.json
  * Preserves user customizations while adding new features like Agent Teams

package/dist/src/init/mcp-generator.js

@@ -55,6 +55,16 @@ export function generateMCPConfig(options) {
     if (config.ruvSwarm) {
         mcpServers['ruv-swarm'] = createMCPServerEntry(['ruv-swarm', 'mcp', 'start'], { ...npmEnv }, { optional: true });
     }
+    // Graphify knowledge graph MCP server (project understanding)
+    if (config.graphify) {
+        mcpServers['graphify'] = {
+            command: 'python',
+            args: ['-m', 'graphify.serve', 'graphify-out/graph.json'],
+            env: {},
+            optional: true,
+            description: 'Knowledge graph for codebase understanding — run `python -m graphify <path>` first',
+        };
+    }
     // Flow Nexus MCP server (cloud features)
     if (config.flowNexus) {
         mcpServers['flow-nexus'] = createMCPServerEntry(['flow-nexus@latest', 'mcp', 'start'], { ...npmEnv }, { optional: true, requiresAuth: true });

package/dist/src/init/types.js

@@ -56,6 +56,7 @@ export const DEFAULT_INIT_OPTIONS = {
         mcp: true,
         runtime: true,
         claudeMd: true,
+        graphify: true,
     },
     hooks: {
         preToolUse: true,
@@ -118,6 +119,7 @@ export const DEFAULT_INIT_OPTIONS = {
         monobrain: true,
         ruvSwarm: false,
         flowNexus: false,
+        graphify: false,
         autoStart: false,
         port: 3000,
     },
@@ -156,6 +158,7 @@ export const MINIMAL_INIT_OPTIONS = {
         mcp: true,
         runtime: true,
         claudeMd: true,
+        graphify: false,
     },
     hooks: {
         ...DEFAULT_INIT_OPTIONS.hooks,
@@ -224,6 +227,7 @@ export const FULL_INIT_OPTIONS = {
         mcp: true,
         runtime: true,
         claudeMd: true,
+        graphify: true,
     },
     skills: {
         core: true,
@@ -247,6 +251,7 @@ export const FULL_INIT_OPTIONS = {
         monobrain: true,
         ruvSwarm: true,
         flowNexus: true,
+        graphify: false,
         autoStart: false,
         port: 3000,
     },