Previously, PROJECT_ROOT was always set to CWD, which broke on
alternative CLIs (e.g. OpenClaw) that set CWD to their own workspace
directory. Now Phase 0 parses $ARGUMENTS for a non-flag directory path
and uses it as PROJECT_ROOT, falling back to CWD when omitted.
Closes#90
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replaces the LLM-generated throwaway regex scripts in Phase 1 of the
file-analyzer with a deterministic script that uses PluginRegistry
(TreeSitterPlugin + all non-code parsers) from @understand-anything/core.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The skill's inline Node.js generator was duplicated from core and missed
the .gitignore seeding and bin/ header fix. Updated the one-liner to read
.gitignore patterns, deduplicate against defaults with trailing-slash
normalization, and remove bin/ from the built-in defaults header comment.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Prevents TypeError crash when LLM batches emit mixed weight types
(e.g. 0.8 vs "0.7") during edge deduplication.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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>
Delete the 5 prompt template files from skills/understand/ now that
they live in agents/. Update auto-update-prompt.md hook to reference
agent definitions instead of deleted prompt files.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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>
- Add all 13 node types (including non-code) to VALID_PREFIXES and TYPE_TO_PREFIX
to prevent valid IDs like config:tsconfig.json from being stripped
- Add fallback normalizeNodeId on edge endpoints not found in idMap, fixing
silent relationship loss when edges use different malformed variants than nodes
- Add DroppedEdge interface with source, target, type, and reason fields so
callers can surface exactly which edges were lost and why
- Use honest Record<string, unknown>[] return types instead of unsafe type casts
- Align SKILL.md complexity aliases with COMPLEXITY_STRING_MAP
- Add 5 new tests for non-code types, cross-variant edges, dropped edge detail,
and validateGraph integration
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Parallel file-analyzer subagents can produce inconsistent node IDs
(project-name prefixed, double-prefixed, bare paths) and invalid
complexity values. Phase 3 ASSEMBLE now normalizes these deterministically
before merging, preventing cascading edge drops and dashboard load failures.
- Add normalize-graph.ts with normalizeNodeId, normalizeComplexity,
and normalizeBatchOutput utilities
- Rewrite SKILL.md Phase 3 with 6-step normalization sequence
- Strengthen file-analyzer prompt with ID format warnings
- Add 32 normalization tests and 2 schema boundary tests
Fix all issues from the 5-agent parallel code review of universal file
type support:
- Parser error handling: add console.warn in JSON/YAML catch blocks,
warn on unbalanced braces in Protobuf/Terraform parsers
- Parser correctness: filter .PHONY special targets in Makefile parser,
handle opening brace on next line in Shell parser, fix per-stage
EXPOSE port assignment in Dockerfile parser
- Graph builder: use nodeType-based ID prefix instead of hardcoded
"file:", warn on unknown definition kinds, detect duplicate node IDs
- Type safety: export NodeType alias, add ServiceInfo.lineRange, type
dashboard color maps as Record<NodeType,...>, refactor
getDirectionalLabel to Record<EdgeType,...>, consolidate NodeCategory
- Schema: add StrictLanguageConfigSchema with extensions/filenames
refinement, fix Infrastructure/Schema-Data category comments
- Agent prompts: fix Jenkinsfile language ID (groovy → jenkinsfile),
fix css.md edge type (configures → related), remove shell.md
Makefile cross-reference
- Tests: 20+ new edge case tests across parsers, graph builder,
language registry, and plugin registry
- Documentation: add JSDoc to all 12 parser classes
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Expand persona filter in GraphView.tsx to show all 9 file-level node
types (file, config, document, service, table, endpoint, pipeline,
schema, resource) instead of only "file", fixing invisible nodes
- Add serves, provisions, and routes edge types with creation criteria
to file-analyzer-prompt.md
- Fix related edge weight from 0.3 to 0.5 to match SKILL.md default
- Add filenames to openapiConfig for proper filename-based detection
- Add TODO comments to kubernetesConfig and jsonSchemaConfig explaining
content-based detection limitations
- Clarify that module/concept types are reserved for higher-level agents
- Update language-registry tests for 38 built-in configs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Phase 1 (SCAN): Include non-code files in scan, add fileCategory to
batch metadata. Phase 2 (ANALYZE): Add batching strategy for non-code
files, group related infra/data/doc files together, pass fileCategory
per file. Phase 4 (ARCHITECTURE): Inject non-code language snippets
(markdown, yaml, dockerfile, sql, etc.), pass all node types and all
edge types to architecture analyzer. Phase 5 (TOUR): Include non-code
nodes in tour candidate pool, pass all edge types for topology analysis.
Update node type reference table (5 -> 13 types), edge type reference
table (18 -> 26 types), edge weight conventions, and inline validation
script to handle file-level non-code node types for layer coverage.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add language context snippets for markdown, yaml, json, sql, dockerfile,
terraform, graphql, protobuf, shell, html, and css. Each snippet follows
the existing typescript.md/python.md pattern with Key Concepts, Notable
File Patterns, Edge Patterns, and Summary Style sections. These snippets
are injected into the architecture analyzer prompt to improve layer
assignments for non-code files.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add 8 new node types (config, document, service, table, endpoint,
pipeline, schema, resource) to valid type list, bringing total to 13.
Add 8 new edge types (deploys, serves, migrates, documents, provisions,
routes, defines_schema, triggers) to valid type list, bringing total to
26. Add quality checks: config nodes should have configures edges, doc
nodes should have documents edges, service nodes should have deploys
edges, etc. Add node type / ID prefix consistency check. Update layer
coverage to include all file-level node types.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Allow non-code files as tour stops: README.md as step 1, Dockerfile,
SQL migrations, CI configs, and other infrastructure files. Add non-code
file inventory computation to the topology script. Add languageLesson
concepts for Dockerfile (multi-stage builds), SQL (normalization), YAML
(CI/CD triggers), Terraform (state management), GraphQL (type system),
Protobuf (backward compatibility), and Kubernetes (deployments). Update
pedagogical flow to weave non-code stops into the narrative naturally.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove the code-only file filter so the scanner discovers non-code files
(.md, .yaml, .json, .sql, .tf, Dockerfile, etc.). Add fileCategory field
to each discovered file (code/config/docs/infra/data/script/markup) with
extension-based category detection logic. Expand language detection table
to cover 26+ file types. Infrastructure tooling detection added to
framework detection step.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- --review at same commit hash skips to Phase 6, reuses existing graph
- Same commit hash without flags now asks user what they'd like to do
instead of silently stopping
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Update importCount metric description to reference batchImportData[file.path].length
instead of "number of import statements" (contradicted "do NOT extract imports" rule)
- Fix duplicate /index.js → /index.jsx in impl plan Task 5 extension variants
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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>
Critical fixes:
- C1: Remove unused treeSitter.nodeTypes from configs and schema — extraction
logic is TS/JS-specific, nodeTypes gave false impression of generality
- C2+C3: Remove blocking temp dir prompt, default to .understand-anything/tmp/,
update all 5 prompt templates to use project-local paths instead of /tmp/
- C4: Fix false-positive framework detection — use "next": (with quotes) for
Next.js, remove cors/body-parser from Express keywords
Important fixes:
- I1: Change FrameworkConfig.language to languages[] array — React/Express/Vue
now correctly listed under both typescript and javascript
- I2: Fix getByExtension case sensitivity — .TS now resolves same as .ts
- I3: languageKeyFromPath returns null instead of throwing for unknown extensions
- I4: Duplicate framework registration is now a no-op instead of corrupting array
- I5: SKILL.md now says "skip silently" when language/framework snippet not found
Also: getForLanguage returns a defensive copy, 3 new tests added (157 total).
- Introduced hooks in `hooks.json` for PostToolUse and SessionStart events to prompt users about knowledge graph updates based on commit and session changes.
- Implemented `change-classifier.ts` to classify updates based on structural changes, including SKIP, PARTIAL_UPDATE, ARCHITECTURE_UPDATE, and FULL_UPDATE actions.
- Added comprehensive tests for change classification in `change-classifier.test.ts` to ensure correct behavior across various scenarios.
- Created `fingerprint.ts` to manage file fingerprints, including content hashing, structural analysis, and comparison of fingerprints to detect changes.
- Developed tests for fingerprint extraction and comparison in `fingerprint.test.ts` to validate functionality and ensure accurate change detection.
- Add blocking step in Phase 0 asking where to write temp files
($PROJECT_ROOT/.understand-anything/tmp/ or /tmp/), with explicit
STOP-and-wait language to prevent premature execution
- Make language/framework file discovery explicit in Phase 2 and
Phase 4 with concrete path examples and ls fallback, fixing
issue where Claude's Search tool couldn't find files in subdirs
- Clean up $TMP_DIR alongside intermediate files in Phase 7
Replace the TypeScript/JavaScript-biased analysis pipeline with a truly
language-agnostic system. The core architecture was already language-neutral
(graph schema, dashboard, search) — the bias lived in agent prompts,
tree-sitter plugin, and language-lesson system.
Core changes:
- LanguageConfig + FrameworkConfig types with Zod validation
- LanguageRegistry (12 languages) and FrameworkRegistry (10 frameworks)
- Config-driven TreeSitterPlugin replacing hardcoded TS/JS grammars
- PluginRegistry now delegates to LanguageRegistry for extension mapping
- Language-lesson system uses config for display names and concepts
Prompt system:
- SKILL.md generalized: dynamic injection of language snippets and
framework addendums instead of hardcoded if/else conditionals
- 12 language prompt snippets (languages/*.md) with concepts, patterns,
frameworks per language
- 10 framework addendums (frameworks/*.md) with canonical file roles,
edge patterns, architectural layers — Django/FastAPI/Flask preserved
and split, plus React/Next.js/Express/Vue/Spring/Rails/Gin added
- Extended entry points, directory patterns, and test patterns across
all 12 language ecosystems in base prompts
The original commit 9fe003a introduced normalization logic in three
separate places (Phase 4 inline, Phase 5 inline, Phase 5.5), creating
an ordering conflict where "do not use field X" rules appeared before
"convert field X to field Y" rules. An LLM following instructions
sequentially could drop legacy fields before converting them.
- Consolidate all layer normalization into Phase 4 as ordered steps
- Consolidate all tour normalization into Phase 5 as ordered steps
- Remove redundant Phase 5.5 entirely
- Fix misleading "from current prompt" comments about envelope format
- Add defensive handling for nodes-as-objects edge case
- Wrap JSON examples in arrays for visual consistency with prompts
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace all named agent dispatches (project-scanner, file-analyzer,
architecture-analyzer, tour-builder, graph-reviewer) with subagent
dispatches using prompt template files. Add context injection for each
phase including README content, package manifest, directory tree,
framework-specific guidance, and cross-validation data.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
0xnayuta
0xnayuta
Lum1104
Sreeram
Sreeram
Aditya