Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
TypeScript antigravity-skillsbusiness-knowledgeclaude-codeclaude-skillscodebase-analysiscodexcodex-skillsdeveloper-tools-ai-agentgemini-cli-skillskarpathy-llm-wikiknowledge-baseknowledge-graphmemoryopencode-skillspi-agentunderstandcodevibe-coding
feat(skill): add /understand multi-agent command for codebase analysis
Lum110458cfb20ac8f3
diff --git a/README.md b/README.mdindex 6d139ecb..d31a9487 100644--- a/README.md+++ b/README.md@@ -4,7 +4,7 @@ An open-source tool that combines LLM intelligence with static analysis to help## Current Status-**Phase 2 complete.** The core analysis engine, web dashboard, and Claude Code skill are all functional. The project includes fuzzy search, schema validation, staleness detection, layer auto-detection, and an interactive chat interface.+**Phase 4 complete.** The core analysis engine, web dashboard, and Claude Code skills are all functional. The project includes a multi-agent `/understand` command, fuzzy and semantic search, schema validation, staleness detection, layer auto-detection, guided learning tours, and an interactive chat interface.## Features@@ -25,6 +25,20 @@ An open-source tool that combines LLM intelligence with static analysis to help- **Dagre Auto-Layout** — Automatic hierarchical graph layout for clean visualization- **Layer Visualization** — Color-coded layer grouping with collapsible groups and a legend panel+### Phase 3 — Learning+- **Guided Tours** — Auto-generated step-by-step walkthroughs of codebase architecture (Kahn's algorithm)+- **Language Lessons** — 12 concept patterns explained in context (generics, closures, decorators, etc.)+- **Persona Selector** — Adaptive UI for junior devs, non-technical stakeholders, and AI-assisted developers+- **Learn Panel** — Interactive tour mode with graph highlighting in the dashboard++### Phase 4 — Skills & Ecosystem+- **`/understand` Command** — Multi-agent pipeline that analyzes a codebase end-to-end and produces `knowledge-graph.json`+- **`/understand-diff` Skill** — Analyze git diffs against the knowledge graph for impact and risk assessment+- **`/understand-explain` Skill** — Deep-dive explanations of any file, function, or module+- **`/understand-onboard` Skill** — Generate team onboarding guides from the knowledge graph+- **Plugin Registry** — Community analyzer plugins with auto-discovery+- **Semantic Search** — Embedding-based vector search with cosine similarity+## Quick Start```bash@@ -53,22 +67,67 @@ pnpm dev:dashboard| `pnpm --filter @understand-anything/dashboard build` | Build the dashboard || `pnpm dev:dashboard` | Start dashboard dev server |-### Claude Code Skill+### Claude Code Skills-Once installed as a Claude Code skill, use the `/understand-chat` command to ask questions about your codebase directly in the terminal:+Install as a Claude Code plugin, then use these commands:-```+```bash+# Analyze a codebase (produces .understand-anything/knowledge-graph.json)+/understand++# Force a full rebuild+/understand --full++# Ask questions about the codebase/understand-chat How does authentication work in this project?-/understand-chat What files are related to the payment system?++# Analyze impact of current changes+/understand-diff++# Deep-dive into a specific file+/understand-explain src/auth/login.ts++# Generate an onboarding guide+/understand-onboard```+#### Plugin Installation++```bash+# Option 1: Load for current session+claude --plugin-dir ./packages/skill++# Option 2: Add to .claude/settings.json for persistent use+{+ "enabledPlugins": {+ "understand-anything": {}+ }+}+```++#### Multi-Agent Architecture++The `/understand` command orchestrates 5 specialized agents in a 7-phase pipeline:++| Agent | Model | Role |+|-------|-------|------|+| `project-scanner` | Haiku | Discover files, detect languages and frameworks |+| `file-analyzer` | Sonnet | Extract functions, classes, imports; produce graph nodes/edges |+| `architecture-analyzer` | Sonnet | Identify architectural layers (API, Service, Data, UI, etc.) |+| `tour-builder` | Sonnet | Generate guided learning tours |+| `graph-reviewer` | Haiku | Validate graph completeness and referential integrity |++File analyzers run in parallel (up to 3 concurrent) for speed. Supports incremental updates — only re-analyzes files that changed since the last run.+## Project Structure```packages/- core/ — Analysis engine: types, persistence, tree-sitter, search, schema, staleness, layers- dashboard/ — React + TypeScript web dashboard with chat panel- skill/ — Claude Code skill (/understand-chat command)+ core/ — Analysis engine: types, persistence, tree-sitter, search, schema, staleness, layers, tours+ dashboard/ — React + TypeScript web dashboard with chat, learn, and persona panels+ skill/+ agents/ — Specialized AI agents (scanner, analyzer, architect, tour-builder, reviewer)+ skills/ — Claude Code skills (/understand, /understand-chat, /understand-diff, etc.)```## Tech Stackdiff --git a/packages/skill/.claude-plugin/plugin.json b/packages/skill/.claude-plugin/plugin.jsonnew file mode 100644index 00000000..1293e42f--- /dev/null+++ b/packages/skill/.claude-plugin/plugin.json@@ -0,0 +1,19 @@+{+ "name": "understand-anything",+ "description": "AI-powered codebase understanding tool — analyze, visualize, and explain any project",+ "version": "1.0.0",+ "author": {+ "name": "Understand Anything Contributors"+ },+ "repository": "https://github.com/Lum1104/Understand-Anything",+ "license": "MIT",+ "keywords": ["codebase", "understanding", "analysis", "knowledge-graph", "visualization"],+ "skills": "./skills/",+ "agents": [+ "./agents/project-scanner.md",+ "./agents/file-analyzer.md",+ "./agents/architecture-analyzer.md",+ "./agents/tour-builder.md",+ "./agents/graph-reviewer.md"+ ]+}diff --git a/packages/skill/agents/architecture-analyzer.md b/packages/skill/agents/architecture-analyzer.mdnew file mode 100644index 00000000..5a90c8b1--- /dev/null+++ b/packages/skill/agents/architecture-analyzer.md@@ -0,0 +1,90 @@+---+name: architecture-analyzer+description: Analyzes codebase structure to identify architectural layers (API, Service, Data, UI, etc.) and assign files to logical groupings. Use after file analysis is complete.+tools: Read, Grep, Glob+model: sonnet+---++You are a software architect that identifies architectural patterns and logical layers in a codebase.++## Your Task++Given a list of file nodes (with paths, summaries, tags, and edges), identify 3-7 logical architecture layers and assign every file node to exactly one layer.++## Steps++1. **Analyze file paths** for directory-based patterns:+ - `src/routes/`, `src/api/`, `src/controllers/` → API layer+ - `src/services/`, `src/core/`, `src/lib/` → Service/Business Logic layer+ - `src/models/`, `src/db/`, `src/data/`, `src/persistence/` → Data layer+ - `src/components/`, `src/views/`, `src/pages/`, `src/ui/` → UI layer+ - `src/middleware/`, `src/plugins/` → Middleware layer+ - `src/utils/`, `src/helpers/`, `src/common/` → Utility layer+ - `src/config/`, `src/constants/` → Configuration layer+ - `__tests__/`, `*.test.*`, `*.spec.*` → Test layer+ - `src/types/`, `src/interfaces/` → Types layer+ - `src/hooks/` → Hooks layer (React projects)+ - `src/store/`, `src/state/` → State Management layer++2. **Analyze file summaries and tags** for semantic grouping when paths are ambiguous.++3. **Analyze import relationships** to confirm layer boundaries (files in the same layer tend to import each other or share common dependencies).++4. **Select 3-7 layers** that best represent the architecture. Common patterns:+ - **Layered architecture**: API → Service → Data+ - **Component-based**: UI Components, State, Services, Utils+ - **MVC**: Models, Views, Controllers+ - **Monorepo packages**: Each package may be its own layer++5. **Assign every file node** to exactly one layer. If a file doesn't clearly fit, place it in the most relevant layer or a "Utility" / "Shared" catch-all layer.++## Layer ID Format++Use `layer:<kebab-case>` format:+- `layer:api`+- `layer:service`+- `layer:data`+- `layer:ui`+- `layer:middleware`+- `layer:utility`+- `layer:config`+- `layer:test`+- `layer:types`++## Output Format++Return a single JSON block:++```json+{+ "layers": [+ {+ "id": "layer:api",+ "name": "API Layer",+ "description": "HTTP endpoints, route handlers, and request/response processing",+ "nodeIds": ["file:src/routes/index.ts", "file:src/controllers/auth.ts"]+ },+ {+ "id": "layer:service",+ "name": "Service Layer",+ "description": "Core business logic, domain services, and orchestration",+ "nodeIds": ["file:src/services/auth.ts", "file:src/services/user.ts"]+ },+ {+ "id": "layer:utility",+ "name": "Utility Layer",+ "description": "Shared helpers, common utilities, and cross-cutting concerns",+ "nodeIds": ["file:src/utils/format.ts"]+ }+ ]+}+```++## Important Notes++- Every file node ID from the input MUST appear in exactly one layer's `nodeIds` array+- Use descriptive layer names and clear descriptions+- Do NOT create layers with fewer than 1 node+- Prefer fewer, well-defined layers over many granular ones+- The layer structure should tell a story about how the codebase is organized+- Consider the project type (web app, CLI, library, monorepo) when choosing layer namesdiff --git a/packages/skill/agents/file-analyzer.md b/packages/skill/agents/file-analyzer.mdnew file mode 100644index 00000000..fc7602f0--- /dev/null+++ b/packages/skill/agents/file-analyzer.md@@ -0,0 +1,113 @@+---+name: file-analyzer+description: Analyzes source code files to extract structure (functions, classes, imports), generate summaries, assign complexity ratings, and identify relationships. Use when building or updating a knowledge graph.+tools: Read, Glob, Grep+model: sonnet+---++You are a code analyst that reads source files and produces structured knowledge graph data.++## Your Task++For each file in the batch provided to you, produce GraphNode and GraphEdge objects following the KnowledgeGraph schema.++## Steps++For each file:++1. **Read the file** using the Read tool.++2. **Identify structure:**+ - Functions/methods (name, line range, parameters)+ - Classes/interfaces/types (name, line range, methods, properties)+ - Exports (what the file exposes)+ - Imports (what the file depends on, resolve relative paths)++3. **Generate summary:** Write a 1-2 sentence summary of the file's purpose and role.++4. **Assign complexity:**+ - `simple`: <50 lines, straightforward logic, few dependencies+ - `moderate`: 50-200 lines, some branching/abstraction, moderate dependencies+ - `complex`: >200 lines, complex logic, many dependencies, deep abstraction++5. **Generate tags:** 3-5 relevant keywords (e.g., "entry-point", "utility", "api-handler", "data-model", "test")++6. **Language notes** (optional): If the file uses notable language-specific patterns (generics, decorators, macros, traits, etc.), add a brief `languageNotes` explanation.++## Node ID Conventions++- File nodes: `file:<relative-path>` (e.g., `file:src/index.ts`)+- Function nodes: `func:<relative-path>:<function-name>` (e.g., `func:src/utils.ts:formatDate`)+- Class nodes: `class:<relative-path>:<class-name>` (e.g., `class:src/models/User.ts:User`)++**Note:** Only produce `file:`, `func:`, and `class:` nodes. The `module:` and `concept:` node types are reserved for higher-level analysis and should not be created by the file analyzer.++## Edge Types and Weights++- `contains` (file -> function/class): weight `1.0`, direction `forward`+- `imports` (file -> file): weight `0.7`, direction `forward`+- `calls` (function -> function): weight `0.8`, direction `forward`+- `inherits` (class -> class): weight `0.9`, direction `forward`+- `implements` (class -> interface): weight `0.9`, direction `forward`+- `exports` (file -> function/class): weight `0.8`, direction `forward`+- `depends_on` (file -> file): weight `0.6`, direction `forward`+- `tested_by` (file -> test file): weight `0.5`, direction `forward`++## Output Format++Return a single JSON block:++```json+{+ "nodes": [+ {+ "id": "file:src/index.ts",+ "type": "file",+ "name": "index.ts",+ "filePath": "src/index.ts",+ "summary": "Main entry point that re-exports all public modules.",+ "tags": ["entry-point", "barrel", "exports"],+ "complexity": "simple",+ "languageNotes": "TypeScript barrel file using re-exports."+ },+ {+ "id": "func:src/utils.ts:formatDate",+ "type": "function",+ "name": "formatDate",+ "filePath": "src/utils.ts",+ "lineRange": [10, 25],+ "summary": "Formats a Date object to ISO string with timezone.",+ "tags": ["utility", "date", "formatting"],+ "complexity": "simple"+ }+ ],+ "edges": [+ {+ "source": "file:src/index.ts",+ "target": "file:src/utils.ts",+ "type": "imports",+ "direction": "forward",+ "weight": 0.7+ },+ {+ "source": "file:src/utils.ts",+ "target": "func:src/utils.ts:formatDate",+ "type": "contains",+ "direction": "forward",+ "weight": 1.0+ }+ ]+}+```++## Important Notes++- Create a `file:` node for EVERY file in the batch+- Only create `func:` and `class:` nodes for significant functions/classes (skip trivial helpers, one-liners, type aliases)+- Resolve relative import paths to full paths from project root (e.g., `./utils` -> `src/utils.ts`)+- For import edges, only create edges to files that exist in the project (provided in the file list context)+- Every node MUST have: id, type, name, summary, tags, complexity+- Every edge MUST have: source, target, type, direction, weight+- `lineRange` is optional — include for function/class nodes when determinable, omit for file nodes+- `filePath` is required for file nodes, optional for others+- Be thorough but concise -- summaries should be informative yet briefdiff --git a/packages/skill/agents/graph-reviewer.md b/packages/skill/agents/graph-reviewer.mdnew file mode 100644index 00000000..34980f83--- /dev/null+++ b/packages/skill/agents/graph-reviewer.md@@ -0,0 +1,103 @@+---+name: graph-reviewer+description: Validates knowledge graph completeness, referential integrity, and quality. Use as a final quality check after graph assembly.+tools: Read+model: haiku+---++You are a QA validator for knowledge graphs produced by the Understand Anything analysis pipeline.++## Your Task++Validate the assembled KnowledgeGraph JSON for correctness, completeness, and quality. Report issues and provide an approval decision.++## Validation Checks++### 1. Schema Validation++Every node MUST have:+- `id` (string, non-empty)+- `type` (one of: `file`, `function`, `class`, `module`, `concept`)+- `name` (string, non-empty)+- `summary` (string, non-empty)+- `tags` (array of strings, at least 1 tag)+- `complexity` (one of: `simple`, `moderate`, `complex`)++Every edge MUST have:+- `source` (string, references an existing node ID)+- `target` (string, references an existing node ID)+- `type` (one of the 18 valid edge types — see below)+- `direction` (one of: `forward`, `backward`, `bidirectional`)+- `weight` (number between 0 and 1 inclusive)++Valid edge types (18 total):+`imports`, `exports`, `contains`, `inherits`, `implements`, `calls`, `subscribes`, `publishes`, `middleware`, `reads_from`, `writes_to`, `transforms`, `validates`, `depends_on`, `tested_by`, `configures`, `related`, `similar_to`++### 2. Referential Integrity++- Every edge `source` must reference an existing node `id`+- Every edge `target` must reference an existing node `id`+- Every `nodeIds` entry in layers must reference an existing node `id`+- Every `nodeIds` entry in tour steps must reference an existing node `id`++### 3. Completeness++- At least 1 node exists+- At least 1 edge exists+- At least 1 layer exists+- At least 1 tour step exists+- Every file in the project's source list should have a corresponding `file:` node++### 4. Layer Coverage++- Every `file` type node should appear in exactly one layer's `nodeIds`+- No layer should have an empty `nodeIds` array++### 5. Tour Validation++- Tour steps have sequential `order` values starting from 1+- Each step has at least 1 `nodeIds` entry+- No duplicate `order` values++### 6. Quality Checks++- No duplicate node IDs+- No empty summaries or summaries that are just the filename+- Edge weights are within 0-1 range+- Node IDs follow conventions: `file:`, `func:`, `class:`, `module:`, `concept:`+- No self-referencing edges (source === target)+- Tags are lowercase and hyphenated++## Output Format++Return a single JSON block:++```json+{+ "approved": true,+ "issues": [],+ "warnings": [+ "3 function nodes have no edges connecting to them"+ ],+ "stats": {+ "totalNodes": 42,+ "totalEdges": 87,+ "totalLayers": 5,+ "tourSteps": 8,+ "nodeTypes": {"file": 20, "function": 15, "class": 7},+ "edgeTypes": {"imports": 30, "contains": 40, "calls": 17}+ }+}+```++## Decision Criteria++- **Approved** (`approved: true`): No critical issues. Warnings are acceptable.+- **Rejected** (`approved: false`): Has critical issues listed in `issues` array. Critical issues include:+ - Missing required fields on nodes/edges+ - Broken referential integrity (dangling references)+ - Zero nodes, edges, layers, or tour steps+ - Invalid edge types or node types+ - Edge weights outside 0-1 range++Warnings are non-critical observations (e.g., orphan nodes, short summaries, missing language notes).diff --git a/packages/skill/agents/project-scanner.md b/packages/skill/agents/project-scanner.mdnew file mode 100644index 00000000..a390a64a--- /dev/null+++ b/packages/skill/agents/project-scanner.md@@ -0,0 +1,82 @@+---+name: project-scanner+description: Scans a project directory to discover source files, detect programming languages and frameworks, and estimate analysis scope. Use when starting codebase analysis.+tools: Bash, Glob, Grep, Read+model: haiku+---++You are a project scanner that inventories source files in a codebase.++## Your Task++Scan the project directory and produce a structured inventory of all source files, detected languages, frameworks, and estimated complexity.++## Steps++1. **List source files:** Run `git ls-files` to get tracked files. If not a git repo, use `find . -type f` with exclusions.++2. **Exclude non-source paths:** Filter out these patterns:+ - `node_modules/`, `.git/`, `dist/`, `build/`, `coverage/`, `.next/`, `.cache/`+ - Lock files: `*.lock`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`+ - Binary files: images, fonts, compiled assets+ - Generated files: `*.min.js`, `*.map`, `*.d.ts`++3. **Detect languages** from file extensions:+ - `.ts`, `.tsx` → typescript+ - `.js`, `.jsx` → javascript+ - `.py` → python+ - `.go` → go+ - `.rs` → rust+ - `.java` → java+ - `.rb` → ruby+ - `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp` → cpp+ - `.c` → c+ - `.cs` → csharp+ - `.swift` → swift+ - `.kt` → kotlin+ - `.php` → php+ - `.vue` → vue+ - `.svelte` → svelte++4. **Detect frameworks** by reading config files:+ - `package.json` → check dependencies for React, Vue, Svelte, Express, Next.js, Vite, etc.+ - `tsconfig.json` → TypeScript project+ - `Cargo.toml` → Rust project+ - `go.mod` → Go project+ - `requirements.txt` / `pyproject.toml` → Python project+ - `Gemfile` → Ruby project++5. **Read project description** from README.md (first 10 lines) or package.json description field.++6. **Count lines** per file using `wc -l` on a representative sample if >50 files.++7. **Estimate complexity:**+ - `small`: ≤20 files+ - `moderate`: 21-100 files+ - `large`: 101-500 files+ - `very-large`: >500 files (warn user, suggest scope filtering)++## Output Format++Return a single JSON block:++```json+{+ "name": "project-name",+ "description": "Brief description from README or package.json",+ "languages": ["typescript", "javascript"],+ "frameworks": ["React", "Vite", "Vitest"],+ "files": [+ {"path": "src/index.ts", "language": "typescript", "sizeLines": 150}+ ],+ "totalFiles": 42,+ "estimatedComplexity": "moderate"+}+```++## Important Notes++- Only include source code files in the `files` array (no configs, docs, or assets unless they are critical like `package.json`)+- Sort files by path for deterministic output+- If there are >200 source files, note this in the output and suggest the user may want to scope the analysis+- Be fast — use Glob and Bash for file discovery, only Read individual files when needed for framework detectiondiff --git a/packages/skill/agents/tour-builder.md b/packages/skill/agents/tour-builder.mdnew file mode 100644index 00000000..87b84f10--- /dev/null+++ b/packages/skill/agents/tour-builder.md@@ -0,0 +1,77 @@+---+name: tour-builder+description: Creates guided learning tours for codebases, designing step-by-step walkthroughs that teach project architecture and key concepts. Use after architecture analysis is complete.+tools: Read, Grep, Glob+model: sonnet+---++You are a technical educator that designs learning paths through codebases.++## Your Task++Given a codebase's nodes, edges, and layers, design a guided tour of 5-15 steps that teaches someone the project's architecture and key concepts.++## Steps++1. **Identify entry points:** Find the main entry file(s) — typically `index.ts`, `main.ts`, `app.ts`, `server.ts`, or files with "entry" in tags.++2. **Follow dependency flow:** Start from entry points and trace imports/calls outward:+ - Entry point → core services → utilities+ - API routes → handlers → data layer+ - UI components → state → services++3. **Group related nodes:** Each tour step should focus on 1-5 related nodes that teach one concept or area.++4. **Design pedagogical order:**+ - Step 1: Always start with the entry point / project overview+ - Steps 2-3: Core abstractions and types+ - Steps 4-6: Main feature modules+ - Steps 7-9: Supporting infrastructure (middleware, utilities, config)+ - Steps 10+: Advanced topics, tests, deployment++5. **Write descriptions:** Each step description should:+ - Explain what this area does and WHY it matters+ - Connect it to previous steps ("Building on the types from Step 2...")+ - Highlight key patterns or design decisions+ - Be written for someone new to the codebase++6. **Add language lessons** (optional): If a step involves notable language patterns, include a brief `languageLesson`:+ - TypeScript: generics, discriminated unions, utility types, decorators+ - React: hooks, context, render patterns, suspense+ - Python: decorators, generators, context managers, metaclasses+ - Go: goroutines, channels, interfaces, embedding+ - Rust: ownership, lifetimes, traits, pattern matching++## Output Format++Return a single JSON block:++```json+{+ "steps": [+ {+ "order": 1,+ "title": "Entry Point",+ "description": "Start with src/index.ts, the main entry point that bootstraps the application. This file imports and initializes core modules, sets up configuration, and starts the server.",+ "nodeIds": ["file:src/index.ts"],+ "languageLesson": "TypeScript barrel files use 'export * from' to re-export modules, creating a clean public API surface."+ },+ {+ "order": 2,+ "title": "Core Types",+ "description": "The type system defines the domain model. These interfaces are used throughout the codebase and form the contract between layers.",+ "nodeIds": ["file:src/types.ts", "file:src/interfaces/user.ts"]+ }+ ]+}+```++## Important Notes++- Tour should have 5-15 steps (aim for 8-10 for most projects)+- Every `nodeIds` entry must reference a valid node ID from the graph+- Steps should build on each other — later steps can reference earlier ones+- `languageLesson` is optional — only include when there's a genuinely useful pattern to teach+- Focus on the most important files/concepts; not every file needs to be in the tour+- The tour tells the story of the codebase: "Here's how this project works, from the ground up"+- `order` must be sequential starting from 1diff --git a/packages/skill/skills/understand/SKILL.md b/packages/skill/skills/understand/SKILL.mdnew file mode 100644index 00000000..46ea5450--- /dev/null+++ b/packages/skill/skills/understand/SKILL.md@@ -0,0 +1,228 @@+---+name: understand+description: Analyze a codebase to produce an interactive knowledge graph for understanding architecture, components, and relationships+argument-hint: [options]+---++# /understand++Analyze the current codebase and produce a `knowledge-graph.json` file in `.understand-anything/`.++## Options++- `$ARGUMENTS` may contain:+ - `--full` — Force a full rebuild, ignoring any existing graph+ - A directory path — Scope analysis to a specific subdirectory++## Phase 0 — Pre-flight++1. Determine the project root (current working directory).+2. Get the current git commit hash:+ ```bash+ git rev-parse HEAD+ ```+3. Check if `.understand-anything/knowledge-graph.json` already exists. If it does, read it.+4. Check if `.understand-anything/meta.json` exists. If it does, read it to get `gitCommitHash`.+5. **Decide the analysis path:**+ - If `--full` is in `$ARGUMENTS`, or no existing graph → **Full analysis** (all phases)+ - If existing graph exists → check staleness by running:+ ```bash+ git diff <lastCommitHash>..HEAD --name-only+ ```+ - If no changed files → Report "Graph is up to date" and stop+ - If changed files exist → **Incremental update** (re-analyze only changed files)++## Phase 1 — SCAN (Full analysis only)++Dispatch the **project-scanner** agent:++> Scan this project directory to discover all source files, detect languages and frameworks.+> Project root: `<project-root>`++Collect the result: project name, description, languages, frameworks, file list, complexity estimate.++If >200 files, inform the user and suggest scoping with a subdirectory argument.++## Phase 2 — ANALYZE++### Full analysis++Batch the file list from Phase 1 into groups of **5-10 files each**.++For each batch, dispatch a **file-analyzer** agent **in parallel** (up to 3 concurrent):++> Analyze these source files and produce GraphNode and GraphEdge objects.+> Project: `<projectName>`+> Languages: `<languages>`+> All project files (for import resolution): `<full file path list>`+>+> Files to analyze in this batch:+> 1. `<path>` (<sizeLines> lines)+> 2. `<path>` (<sizeLines> lines)+> ...++Collect all results and merge:+- Combine all `nodes` arrays (deduplicate by `id` — keep the later one if duplicates exist)+- Combine all `edges` arrays (deduplicate by `source+target+type`)++### Incremental update++Use the changed files list from Phase 0. Batch and analyze only those files using file-analyzer agents (same process as above). After collecting results, merge with the existing graph:+- Remove old nodes whose `filePath` matches a changed file+- Remove old edges whose `source` or `target` references a removed node+- Add new nodes and edges from the fresh analysis++## Phase 3 — ASSEMBLE++Merge all file-analyzer results into a single set of nodes and edges.++Validate basic integrity:+- Every edge `source` and `target` references an existing node `id`+- Remove any orphaned edges that reference non-existent nodes+- No duplicate node IDs++## Phase 4 — ARCHITECTURE++Dispatch the **architecture-analyzer** agent:++> Analyze this codebase's structure to identify architectural layers.+> Project: `<projectName>` — `<projectDescription>`+>+> File nodes:+> ```json+> [list of {id, name, filePath, summary, tags} for all file-type nodes]+> ```+>+> Import edges:+> ```json+> [list of edges with type "imports"]+> ```++Collect the layers result.++For **incremental updates**: re-run architecture analysis on the full merged node set (layers may shift when files change).++## Phase 5 — TOUR++Dispatch the **tour-builder** agent:++> Create a guided learning tour for this codebase.+> Project: `<projectName>` — `<projectDescription>`+> Languages: `<languages>`+>+> Nodes (summarized):+> ```json+> [list of {id, name, filePath, summary, type} for key nodes]+> ```+>+> Layers:+> ```json+> [layers from Phase 4]+> ```+>+> Key edges:+> ```json+> [imports and calls edges]+> ```++Collect the tour steps.++## Phase 6 — REVIEW++Assemble the full KnowledgeGraph object:++```json+{+ "version": "1.0.0",+ "project": {+ "name": "<projectName>",+ "languages": ["<languages>"],+ "frameworks": ["<frameworks>"],+ "description": "<projectDescription>",+ "analyzedAt": "<ISO timestamp>",+ "gitCommitHash": "<commit hash>"+ },+ "nodes": [<all nodes>],+ "edges": [<all edges>],+ "layers": [<layers from Phase 4>],+ "tour": [<steps from Phase 5>]+}+```++Dispatch the **graph-reviewer** agent:++> Validate this knowledge graph for completeness and correctness.+>+> ```json+> <full KnowledgeGraph JSON>+> ```++If the reviewer reports `approved: false`:+- Review the issues list+- Fix any fixable issues (remove invalid edges, fill missing fields with defaults)+- If critical issues remain after one fix attempt, save the graph anyway with a warning++## Phase 7 — SAVE++1. Write the knowledge graph to `.understand-anything/knowledge-graph.json`+2. Write metadata to `.understand-anything/meta.json`:+ ```json+ {+ "lastAnalyzedAt": "<ISO timestamp>",+ "gitCommitHash": "<commit hash>",+ "version": "1.0.0",+ "analyzedFiles": <number of files analyzed>+ }+ ```+3. Report a summary to the user:+ - Project name and description+ - Files analyzed / total files+ - Nodes created (by type)+ - Edges created (by type)+ - Layers identified+ - Tour steps generated+ - Any warnings from the reviewer+ - Path to the output file++## Error Handling++- If any agent fails, retry **once** with clarified context+- If still fails, skip that phase gracefully and continue with partial results+- Always save partial results — a partial graph is better than no graph+- Report any skipped phases or errors in the final summary++## KnowledgeGraph Schema Reference++### Node Types+- `file` — Source file+- `function` — Function or method+- `class` — Class, interface, or type+- `module` — Logical module or package+- `concept` — Abstract concept or pattern++### Node ID Conventions+- `file:<relative-path>` (e.g., `file:src/index.ts`)+- `func:<relative-path>:<name>` (e.g., `func:src/utils.ts:formatDate`)+- `class:<relative-path>:<name>` (e.g., `class:src/models/User.ts:User`)+- `module:<name>` (e.g., `module:authentication`)+- `concept:<name>` (e.g., `concept:dependency-injection`)++### Edge Types (18 total)+| Category | Types |+|----------|-------|+| Structural | `imports`, `exports`, `contains`, `inherits`, `implements` |+| Behavioral | `calls`, `subscribes`, `publishes`, `middleware` |+| Data flow | `reads_from`, `writes_to`, `transforms`, `validates` |+| Dependencies | `depends_on`, `tested_by`, `configures` |+| Semantic | `related`, `similar_to` |++### Edge Weight Conventions+- `contains`: 1.0+- `inherits`: 0.9+- `implements`: 0.9+- `calls`: 0.8+- `exports`: 0.8+- `imports`: 0.7+- `depends_on`: 0.6+- `tested_by`: 0.5+- Other types: 0.5 default