Understand-Anything

feat(skill): add /understand multi-agent command for codebase analysis

Implements the main /understand skill that orchestrates 5 specialized
agents in a 7-phase pipeline to analyze codebases and produce
knowledge-graph.json. Supports full and incremental analysis modes.

- project-scanner (haiku): file discovery, language/framework detection
- file-analyzer (sonnet): code structure extraction, node/edge generation
- architecture-analyzer (sonnet): architectural layer identification
- tour-builder (sonnet): guided learning tour generation
- graph-reviewer (haiku): graph validation and quality checks

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-15 00:04:11 +08:00

58cfb20ac8

feat(dashboard): add fuzzy/semantic search mode toggle

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 23:18:59 +08:00

0c5411e282

feat(core): add embedding-based semantic search engine

Add SemanticSearchEngine class that stores pre-computed vector embeddings
for graph nodes and performs cosine similarity search. Enables true semantic
queries (e.g., "find code that handles authentication") even when keywords
don't appear in node data. Returns the same SearchResult type as the
existing Fuse.js-based SearchEngine for compatibility.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 23:16:10 +08:00

ae5b4de3d9

feat(core): add plugin configuration and discovery system

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 23:11:28 +08:00

6224761359

feat(core): add plugin registry for community analyzer plugins

Introduces PluginRegistry class that discovers, registers, and manages
analyzer plugins. Maps file extensions to languages, provides a unified
analyzeFile entrypoint, and supports plugin priority via registration
order. Foundation for the community plugin system.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 23:04:56 +08:00

f977ce8a48

feat(skill): add /understand-onboard command for team onboarding guides

Generates a structured markdown onboarding guide from the knowledge graph,
including project overview, architecture layers, key concepts, guided tour,
file map, and complexity hotspots.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 22:49:37 +08:00

09fc78f321

feat(skill): add /understand-explain command for deep-dive file analysis

Adds the explain-builder module that constructs rich context for explaining
a specific file or function. Supports file paths and path:function notation,
gathers child nodes, connected components, layer membership, and formats
a structured prompt for LLM-powered deep-dive explanations.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 22:31:09 +08:00

eb0d2eaac0

feat(skill): add /understand-diff command for PR/diff analysis

Adds buildDiffContext and formatDiffAnalysis to map git diffs against
the knowledge graph, identifying changed nodes, affected components,
impacted layers, and risk assessment. Includes 11 tests and skill
definition for Claude Code integration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 22:13:41 +08:00

e69acffd06

feat(dashboard): add persona mode system with adaptive layouts

Three persona modes change the dashboard experience:
- Overview (non-technical): 2-column layout with graph + learn/chat,
  hides CodeViewer, filters graph to concept/module/file nodes only
- Learn (junior): full 4-panel layout with tabbed Details/Tour panel
- Deep Dive (experienced): full 4-panel layout with NodeInfo, tour
  tabs only shown when tour is explicitly active

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 21:11:52 +08:00

5628c2ed82

feat(dashboard): upgrade languageNotes to collapsible Language Concepts section

Replace plain blue box with indigo-themed collapsible panel featuring
chevron toggle, matching the indigo design language used in LearnPanel.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 21:01:03 +08:00

ccdc4b723f

feat(dashboard): add tour highlight to graph nodes

Wire tourHighlightedNodeIds from the store into GraphView and CustomNode
so that nodes referenced by the current tour step get a pulsing blue ring,
visually distinct from the white selection ring and yellow search rings.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 20:56:38 +08:00

4452fe8e7b

feat(core): add language lesson prompt builder for contextual code teaching

Add detectLanguageConcepts, buildLanguageLessonPrompt, and
parseLanguageLessonResponse to support language-specific lessons tied
to individual graph nodes. Includes 12 concept detection patterns
(async/await, generics, middleware, etc.) and structured LLM prompt
generation with JSON response parsing. 10 new tests, 104 total passing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 20:48:04 +08:00

3b298c1a7a

feat(dashboard): add contextual node explanation with Claude API

Add "Explain This" button to NodeInfo panel that generates a detailed
plain-English explanation of the selected node using Claude API. Explanations
are cached per node ID and cleared on node switch.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 20:38:29 +08:00

8747ed30b4

fix(dashboard): extract tour sort helper and use proper store selectors

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 20:33:15 +08:00

46f02ab7c6

feat(dashboard): add LearnPanel component and tour store state

Add tour state management (tourActive, currentTourStep, tourHighlightedNodeIds)
to the Zustand store with start/stop/navigate actions. Create LearnPanel
component with three states: no tour, tour preview, and active tour with
step navigation, markdown descriptions, language lesson boxes, and
referenced component pills. Replace bottom-right panel in App.tsx with
tabbed Details/Tour view when a tour is available.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 20:23:03 +08:00

f9da9c40cd

feat(core): add tour generation engine with LLM and heuristic strategies

Add three exported functions for generating guided codebase tours:
- buildTourGenerationPrompt: builds LLM prompt with project metadata
- parseTourGenerationResponse: parses LLM JSON response with validation
- generateHeuristicTour: topology-based tour using Kahn's algorithm,
  with layer grouping and concept node separation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 20:13:11 +08:00

cb3d860fe2

docs: add Phase 3 (Learn Mode) and Phase 4 (Advanced) implementation plans

Phase 3 (7 tasks): Tour generation engine, LearnPanel + tour store,
tour player with graph highlighting, contextual node explanations,
language lesson prompts, enhanced language display, persona modes.

Phase 4 (7 tasks): /understand-diff, /understand-explain,
/understand-onboard skills, plugin registry + discovery,
embedding-based semantic search + dashboard integration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 20:03:12 +08:00

45bbbe1557

docs: update sample data, CLAUDE.md, and README for Phase 2

Rich sample knowledge graph with 20 nodes (all 5 types), 28 edges
(10 edge types), 5 layers, and 6 tour steps themed as a task
management API. Updated CLAUDE.md with skill commands and Phase 2
feature list. Updated README with current status, Phase 2 features,
commands table, and skill usage instructions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 19:43:05 +08:00

014c95c086

fix(dashboard): extract shared node dimension constants to layout utility

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 19:36:48 +08:00

d6d937e53b

feat(dashboard): add layer visualization with grouping and legend

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 19:32:05 +08:00

9f16c2c0e5

fix(dashboard): add markdown rendering for chat messages and API key management

- Render assistant messages with ReactMarkdown (headers, code blocks,
  lists, bold, links, blockquotes) instead of plain whitespace-pre-wrap
- Add "Change Key" button in chat header to clear and re-enter API key
- Document the plain-text localStorage tradeoff for API key storage

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 19:26:48 +08:00

0daac92c80

feat(dashboard): add context-aware chat panel with Claude API integration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 19:20:46 +08:00

bd53455f31

fix(dashboard): add score-based highlight intensity and memoize search nodeMap

Pass search score through to CustomNode for tiered ring highlighting
(bright/medium/dim based on score), and wrap SearchBar's nodeMap in
useMemo to avoid rebuilding it on every render.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 19:15:46 +08:00

c3bece91fc

feat(dashboard): wire core SearchEngine with fuzzy matching and scored highlighting

Replace manual substring search in Zustand store with core SearchEngine
(Fuse.js fuzzy matching). SearchBar now shows a top-5 dropdown with type
badges and relevance bars; closes on Escape/outside click. GraphView
updated to work with SearchResult[] (nodeId+score) instead of string[].
Added sub-path exports to core package.json so the dashboard can import
search/types modules without pulling in Node.js-only dependencies.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 19:09:57 +08:00

4f6214a5ce

feat(skill): scaffold skill package with /understand-chat command

Add the @understand-anything/skill package with context-builder (search +
1-hop expansion + layer resolution), chat prompt builder, skill definition
for Claude Code, and 14 passing tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 19:00:54 +08:00

b6ab0f8b32

fix(core): add __tests__ pattern and handle filePath-less nodes in applyLLMLayers

Add __tests__ and __specs__ (plural inside underscores) to Test Layer
patterns for the common convention. Also assign file nodes without
filePath to "Other" layer in applyLLMLayers for consistency.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 18:55:57 +08:00

839166b229

feat(core): add heuristic and LLM-based layer auto-detection

Add layer-detector module with four exported functions:
- detectLayers: heuristic detection using directory path patterns
- buildLayerDetectionPrompt: generates LLM prompt for layer identification
- parseLayerDetectionResponse: parses LLM JSON response with fence handling
- applyLLMLayers: applies LLM-provided layer definitions to the graph

Includes 10 tests covering all four functions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 18:51:19 +08:00

305fb4055b

fix(core): use execFileSync to prevent shell injection and remove dangling edges in merge

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 18:47:33 +08:00

8876eec80e

feat(core): add staleness detection and incremental graph merging

Add staleness module with three functions:
- getChangedFiles: runs git diff to find files changed since last analysis
- isStale: checks whether the knowledge graph needs re-analysis
- mergeGraphUpdate: incrementally merges new analysis into existing graph
  by replacing nodes/edges for changed files while preserving unchanged ones

Includes 8 tests covering git interaction, error handling, and graph merging.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 18:43:01 +08:00

19357d25a3

fix(dashboard): fix import extension and add dagre node position guard

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 18:40:21 +08:00

510de2eb1d

feat(dashboard): add dagre auto-layout for hierarchical graph visualization

Replace grid-based node positioning with dagre-powered hierarchical layout
that computes positions based on edge direction (top-to-bottom). This
produces clean, readable graphs instead of the previous chaotic grid pattern.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 18:35:52 +08:00

dd252eddc0

feat(core): add fuzzy search engine with Fuse.js

Add SearchEngine class with fuzzy matching across node name, tags,
summary, and languageNotes fields. Supports type filtering, result
limiting, and dynamic re-indexing via updateNodes(). Uses Fuse.js
extended search with OR-token splitting for multi-word queries.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 18:29:33 +08:00

a243a07d6f

fix(core): return validated data from loadGraph and fix edge type count comment

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 18:25:33 +08:00

b41cf15ce9

feat(core): add Zod schema validation for knowledge graph loading

Add runtime validation of knowledge graph JSON using Zod schemas that
mirror every type in types.ts. The loadGraph function now validates
by default (opt-out via { validate: false }) and throws descriptive
errors on invalid data.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 18:21:24 +08:00

c04123366e

docs: add README and CLAUDE.md with project overview and conventions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 18:02:26 +08:00

bfd06a704d

feat(dashboard): add search bar, node info, and main 4-panel layout

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 17:58:01 +08:00

7345d83376

feat(dashboard): add code viewer panel with Monaco Editor

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 17:57:53 +08:00

b07bdc2fb9

feat(dashboard): add graph view with React Flow and custom nodes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 17:57:40 +08:00

377c3c72e6

feat(dashboard): scaffold React + Vite app with Tailwind, Zustand, and core dependency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 17:51:50 +08:00

39dfffc4f4

feat(core): add graph builder and LLM analysis prompt system

Add GraphBuilder class that assembles KnowledgeGraph from file analysis
results, with support for file/function/class nodes and import/call/contains
edges. Add LLM prompt templates for file and project analysis, along with
robust JSON response parsers that handle markdown fences and invalid input.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 17:47:40 +08:00

e1fd03ec38

feat(core): add tree-sitter analyzer plugin for TS/JS

Add TreeSitterPlugin using web-tree-sitter (WASM-based) to extract
structural information from TypeScript and JavaScript files. The plugin
implements the AnalyzerPlugin interface and extracts functions, classes,
imports, exports, and call graphs via AST traversal.

Uses web-tree-sitter instead of native tree-sitter for cross-platform
compatibility (no native compilation required).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 17:40:29 +08:00

801c5e7af3

feat(core): add JSON persistence for knowledge graph and meta

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 17:30:23 +08:00

a5327ce64d

feat(core): add knowledge graph type system and validation tests

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 17:25:49 +08:00

35d0545100

fix: improve gitignore security patterns and clean root tsconfig

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 17:22:54 +08:00

7fb8c5cbb8

chore: scaffold monorepo root with pnpm workspaces

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 17:19:44 +08:00

6d5eccf47c

docs: add design doc and Phase 1 implementation plan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-14 17:15:51 +08:00

5d20a57971

46 Commits