68 Commits

This Branch

This Branch

All Branches

• Merge pull request #1 from Lum1104/feat/script-augmented-agents

  feat(agents): script-augmented two-phase architecture

  Yuxiang Lin · 2026-03-17 11:29:39 +08:00
  449a4f01cb
• fix(graph-reviewer): remove duplicated critical checks from warning section

  Edge weights, node ID prefix conventions, and tag formatting were listed
  in both Check 1 (Schema Validation — Critical) and Check 7 (Quality —
  Warning). A deterministic script following check headings would classify
  these as warnings, potentially approving invalid graphs. Remove the
  duplicates from Check 7 since Check 1 already covers them as critical.
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-17 11:28:29 +08:00
  70b4e6fe0a
• fix(agents): define .sh as supported source extension in project-scanner

  The exclusion rule conditionally kept .sh files for bash-first projects,
  but the source-file whitelist and language mapping table had no .sh entry,
  causing retained shell files to be dropped or untyped. Add .sh/.bash to
  the whitelist and language table (mapped to 'bash'), and remove the
  conditional exclusion rule.
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-17 11:13:18 +08:00
  3715552875
• fix(graph-reviewer): align duplicate-ID classification as critical

  Duplicate node IDs were listed under Check 6 (Warning) but classified as
  critical in the Severity Classification section. A script following check
  headings would classify duplicates as warnings, letting invalid graphs
  pass review. Move duplicate-ID check to its own Check 5 (Critical) and
  renumber subsequent checks.
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-17 11:12:29 +08:00
  f5b9eb7d61
• chore: bump version to 1.0.5

  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-17 11:10:14 +08:00
  b9b48466c3
• feat(agents): add script-augmented two-phase architecture to all agents

  Redesign all 5 agent prompts with a "Phase 1 — Script" + "Phase 2 — LLM
  Reasoning" structure. Agents now write and execute scripts for deterministic
  work (validation, file discovery, structure extraction, graph analysis)
  before applying LLM judgment for semantic tasks (summaries, tags, pedagogy).
  
  Key changes per agent:
  - graph-reviewer: script performs all 6 validation checks deterministically
  - project-scanner: script handles file discovery, language detection, line counting
  - file-analyzer: script extracts functions/classes/imports via regex patterns
  - architecture-analyzer: script computes import adjacency, inter-group frequency
  - tour-builder: script calculates fan-in, BFS traversal, cluster detection
  
  Design safeguards:
  - scriptCompleted sentinel field guards against partial script output
  - Batch-indexed temp paths prevent collision in concurrent file-analyzer agents
  - Explicit "trust the script" directives prevent LLM from re-reading raw data
  - Up to 2 script retries on failure
  - Explicit instructions to strip intermediate fields from final output
  - Bash tool added to all agent tool lists
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Lum1104 · 2026-03-16 18:17:02 +08:00
  6af00c5f85
• fix(dashboard): enable click and expand for all node types (function, class, etc.)

  Previously only FILE nodes responded to clicks with the code viewer overlay.
  Now all node types open the detail viewer on click. Also added a direct click
  handler on CustomNode to fix click events not firing for child nodes inside
  group layers on Windows.
  
  Bump version to 1.0.4.

  Lum1104 · 2026-03-16 14:34:11 +08:00
  b82efea88e
• fix: resolve plugin installation failures for workspace resolution and missing dependencies

  Add Vite resolve aliases for core subpath exports (schema, search, types)
  to fix import resolution on Windows where Node.js package exports are not
  properly followed by Vite's import analysis.
  
  Bump version to 1.0.3.
  
  Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

  Lum1104 · 2026-03-16 12:23:48 +08:00
  5c0afb35ff
• fix(ci): use root pnpm-lock.yaml for cache and install from workspace root

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

  Lum1104 · 2026-03-15 20:34:47 +08:00
  4e9539b20d
• fix(ci): add workflow file to trigger paths so CI changes re-run

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

  Lum1104 · 2026-03-15 20:31:15 +08:00
  f57cd9db7b
• fix(ci): remove explicit pnpm version to use packageManager field

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

  Lum1104 · 2026-03-15 20:29:48 +08:00
  d08eeb072d
• feat(homepage): add cinematic project homepage with GitHub Pages deployment

  Astro-based static homepage with dark luxury theme, self-hosted fonts,
  scroll-reveal animations, and GitHub Actions CI/CD to Pages.
  
  Sections: Nav, Hero, Dashboard Showcase, Feature Cards, Install CTA, Footer.
  
  Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

  Lum1104 · 2026-03-15 20:26:49 +08:00
  e862b9a1da
• fix: resolve plugin installation failures for workspace resolution and missing dependencies

  - Add pnpm-workspace.yaml to plugin distribution so workspace:* deps resolve on install
  - Add devlop and hast-util-to-jsx-runtime as explicit dashboard dependencies (pnpm strict hoisting)
  - Make tsconfig.json files self-contained to work outside monorepo root
  - Add prepare script to auto-build core package after pnpm install
  - Bump version to 1.0.2

  Lum1104 · 2026-03-15 19:12:55 +08:00
  bdf6cf6856
• fix: remove nested .claude-plugin/plugin.json to fix user-scope marketplace installation

  The nested plugin.json inside understand-anything-plugin/.claude-plugin/
  conflicted with the root marketplace.json, causing Claude Code to fail
  when installing the plugin in user scope with "Source path does not exist" error.
  
  Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

  Lum1104 · 2026-03-15 17:21:02 +08:00
  99840b16a0
• docs: add hero image and dashboard screenshot to README
  Lum1104 · 2026-03-15 16:53:55 +08:00
  dda6547809
• docs: update CLAUDE.md with current architecture and versioning guide

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

  Lum1104 · 2026-03-15 12:40:07 +08:00
  ded60f8116
• feat: redesign dashboard with dark luxury theme, improve agent pipeline

  - Remove ChatPanel and @anthropic-ai/sdk dependency (redundant with /understand-chat)
  - Replace Monaco editor with styled summary code viewer
  - New graph-first layout: 75% graph + 360px right sidebar
  - Dark luxury aesthetic: deep blacks, gold/amber accents, DM Serif Display typography
  - Add ProjectOverview component for sidebar default state
  - Learn persona now shows tour panel directly in sidebar
  - Add schema validation on graph load with error banner
  - Defensive null checks in store for tour methods
  - Agent pipeline: write intermediate results to disk instead of context
  - Agent models: sonnet for simple tasks, opus for complex (no haiku)
  - Prompt-engineer all 5 agent prompts and SKILL.md
  - Auto-trigger /understand-dashboard after /understand completes
  - Add dashboard screenshot to README
  - Bump version to 1.0.1
  
  Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

  Lum1104 · 2026-03-15 12:36:39 +08:00
  343e94c9a7
• feat(skill): add smart graph reading protocol to query skills

  Replace "read the whole graph file" instructions with targeted Grep-based
  reading in /understand-chat, /understand-diff, /understand-explain, and
  /understand-onboard. Each skill now includes a Graph Structure Reference
  and extracts only the relevant subgraph (matched nodes + 1-hop edges)
  instead of dumping the entire JSON into context. Also update /understand
  to reference /understand-dashboard.
  
  Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

  Lum1104 · 2026-03-15 11:16:55 +08:00
  00d9919ba3
• feat(skill): add /understand-dashboard skill to launch visualization

  New skill command that starts the Vite dev server to visualize the
  knowledge graph in a web dashboard.
  
  Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

  Lum1104 · 2026-03-15 11:16:48 +08:00
  fe50941da4
• refactor: restructure monorepo into Claude Code plugin layout

  Move packages/{core,dashboard,skill} into understand-anything-plugin/ to
  conform to the Claude Code plugin format. Add .claude-plugin/marketplace.json
  for plugin discovery. Update workspace config and docs accordingly.
  
  Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

  Lum1104 · 2026-03-15 11:16:43 +08:00
  b75235919e
• fix(dashboard): auto-detect knowledge graph from .understand-anything/

  The Vite dev server now looks for .understand-anything/knowledge-graph.json
  in the project root, so users don't need to manually copy the graph file
  into public/. Also updates README with clearer installation and usage
  instructions, and adds dashboard viewing steps to /understand SKILL.md.
  
  Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

  Lum1104 · 2026-03-15 00:30:34 +08:00
  f69ad5887e
• chore(skill): migrate skills to plugin format and update docs

  Move existing skills from .claude/skills/ to skills/*/SKILL.md plugin
  format. Update CLAUDE.md to reflect all skill commands. Add phase 2
  implementation plan.
  
  Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

  Lum1104 · 2026-03-15 00:05:14 +08:00
  8e13f77e23
• 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