Understand-Anything

feat: file-analyzer uses bundled tree-sitter script instead of LLM-generated regex

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

Lum1104 · 2026-04-15 19:26:39 +08:00

20c1567143

Merge branch 'main' into feat/understandignore

Lum1104 · 2026-04-12 11:34:10 +08:00

bc311c80ad

feat: add /understand-knowledge for Karpathy LLM wiki knowledge bases

Support the Karpathy LLM wiki pattern — a three-layer architecture
(raw sources + wiki markdown + schema) with wikilinks, index.md
categories, and append-only log.md.

Pipeline:
- parse-knowledge-base.py: deterministic extraction of articles,
  wikilinks, categories from index.md, source nodes from raw/
- article-analyzer agent: LLM-based entity/claim extraction and
  implicit relationship discovery (builds_on, contradicts, etc.)
- merge-knowledge-graph.py: combines scan + analysis with entity
  dedup, layer assignment from categories, tour generation

Dashboard:
- KnowledgeGraphView with d3-force layout (community clustering
  by index.md categories, degree-proportional sizing)
- 5 knowledge node types (article, entity, topic, claim, source)
- 6 knowledge edge types with visual styling
- KnowledgeNodeDetails sidebar (wikilinks, backlinks, preview)
- Auto-detect kind:"knowledge" → knowledge-only view mode

Core:
- 5 node types + 6 edge types added to NodeType/EdgeType unions
- KnowledgeMeta interface (wikilinks, backlinks, category, content)
- kind field on KnowledgeGraph for view mode detection
- Zod schemas + node/edge type aliases

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

Lum1104 · 2026-04-12 11:09:41 +08:00

2fc85e68c3

fix: address code review — remove bin/ from defaults, fix negation override flow

- Remove bin/ from DEFAULT_IGNORE_PATTERNS (Node/Ruby CLI launchers use bin/)
- .NET users can add bin/ to .understandignore manually
- Fix project-scanner Step 2.5 to re-filter from original file list when
  .understandignore exists, ensuring ! negation correctly overrides defaults

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

Lum1104 · 2026-04-10 11:51:59 +08:00

d3de6dc1fd

feat(agent): add .understandignore support and bin/obj exclusions to project-scanner

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

Lum1104 · 2026-04-10 11:38:23 +08:00

3e27a4a8d4

fix: address PR #71 review findings and bump version to 2.2.0

Fix all actionable code review items: add missing domain/flow/step node
types, fix batch numeric sorting, align gate thresholds, merge duplicate
tour steps instead of dropping, add Writing Results section to
assemble-reviewer, use skill-relative script paths, and add func→function
type mapping.

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

Lum1104 · 2026-04-04 12:28:20 +08:00

52050e40cb

feat: add graph merge scripts and improve agent pipeline reliability

Add Python scripts to merge knowledge graphs (closes #70) and move
mechanical normalization out of LLM context into deterministic scripts
with diagnostic reporting. Convert all agent definitions from dispatch
templates to self-contained system prompts to prevent instruction loss.

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

Lum1104 · 2026-04-04 11:56:58 +08:00

b3683d62e2

fix: address all 24 prompt engineering audit issues across 7 agents

knowledge-graph-guide.md (6 issues):
- Fix node types (5→16), edge types (18→29), tour schema (nodeId→nodeIds)
- Add domain graph documentation, jq examples, expand content

graph-reviewer.md (5 issues):
- Add domain node types (domain/flow/step) and edge types (contains_flow/flow_step/cross_domain)
- Relax layers/tour requirements for domain graphs
- Soften Check 8 (remove overly strict config/resource/endpoint checks)

domain-analyzer.md (6 issues):
- Add input format specification, output file path, writing results section
- Add critical constraints section with validation rules
- Fix flow_step weight scheme to stay within 0-1 range
- Change from "respond with JSON" to write-to-file pattern

file-analyzer.md (6 issues):
- Fix node type count description (13→accurate text)
- Recommend Node.js over bash for extraction scripts
- Replace "validate mentally" with actionable JSON validation instruction
- Clarify exports vs contains edge relationship
- Trim redundant tag guidance section
- Document why direction is always forward

architecture-analyzer.md (4 issues):
- Allow Python fallback for script language
- Clarify allEdges excludes sub-file edges
- Define "common prefix" algorithm for directory grouping
- Add layer count validation and empty group handling

tour-builder.md (2 issues):
- Fix BFS to start from code entry point, not README
- Allow Python fallback for script language

project-scanner.md (4 issues):
- Clarify exclusions match full directory segments, not substrings
- Stop excluding *.d.ts (may be hand-written)
- Add .env secret leak warning
- Document $PROJECT_ROOT variable, prefer Node.js

Cross-agent (3 issues):
- Consistent "prefer Node.js; fall back to Python" across all agents
- Schema type/count consistency across all agents
- Domain graph compatibility with graph-reviewer

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

Lum1104 · 2026-04-02 23:14:29 +08:00

fece84ac59

fix: tone down function/class extraction constraint to avoid false mandate

The previous wording ("MUST have sub-nodes") implied every code file
must produce function nodes, which is wrong for files without significant
functions. Now correctly states: if significant functions exist in the
script output, you must create nodes for them.

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

Lum1104 · 2026-04-02 22:54:31 +08:00

2387649c1b

refactor: move prompt templates to agent definitions for prompt integrity

Prompt templates (file-analyzer, project-scanner, architecture-analyzer,
tour-builder, graph-reviewer) were being compressed by the orchestrator
when dispatched as subagent prompts, causing function/class extraction
to be silently skipped. Moving them to agents/ ensures the framework
loads the full prompt without compression.

- Move 5 prompt templates from skills/understand/ to agents/
- Update SKILL.md to reference agent definitions instead of templates
- Set all agent models to `inherit` for cross-platform compatibility
- Update CLAUDE.md to reflect new agent model policy

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

Lum1104 · 2026-04-02 22:21:55 +08:00

52a68e5bd4

feat(agents): add domain-analyzer agent for business domain extraction

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

Lum1104 · 2026-04-02 14:26:06 +08:00

c97096dd96

fix: normalize LLM-generated type aliases before schema validation

LLMs systematically abbreviate node types (e.g. "func" instead of
"function") and edge types (e.g. "extends" instead of "inherits"),
causing dashboard validation failures. This combines two fixes:

Option A: Rename the ambiguous `func:` ID prefix to `function:` across
all prompts, source code, tests, and example data so LLMs see consistent
naming. Also fix `relates_to` ghost edge type in django.md.

Option B: Add NODE_TYPE_ALIASES and EDGE_TYPE_ALIASES normalization maps
in schema.ts that transparently correct common abbreviations before Zod
validation, as a runtime safety net.

Closes #36

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

Lum1104 · 2026-03-25 09:25:42 +08:00

1a16b0fdd6

feat: add knowledge-graph-guide agent for graph navigation and querying

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

Lum1104 · 2026-03-19 10:32:03 +08:00

84d0462e20

refactor: move pipeline agents into skills/understand/ as prompt templates

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

Lum1104 · 2026-03-19 10:31:22 +08:00

5e85a23aa2

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

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

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

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

20 Commits