build-dependency-graph

name	build-dependency-graph
description	Systematically enumerate import and call relationships across a codebase, build a structured dependency graph, and emit both dependency-graph.yaml (structured data) and dependency-graph.md (mermaid diagrams + module clusters). Used by tech-architect.
user-invocable	false
model	sonnet
allowed-tools	Read, Write, Grep, Glob, Bash
deprecated	true
deprecated_note	#434 ProductOS realignment — superseded by the command model; retained for Phase E reference, not installed

build-dependency-graph

Model-invocable skill for structured dependency-graph artifact authorship.

Purpose

Walk import/require/use statements across a codebase, collapse to module-level edges, and write a structured graph plus a visual representation. Emit two artifacts: dependency-graph.yaml (data) and dependency-graph.md (mermaid + narrative).

Previously carved out of tech-architect as a "core architect capability." This skill owns it now.

Input

Field	Required	Description
project_root	yes	Codebase root
focus_paths	optional	Sub-paths to include (default: all source dirs)
language_hint	optional	Language(s) present: py, ts, js, go, java, ... (otherwise auto-detect)
output_base	yes	Directory to write both artifacts

Process

1. Detect language(s). From extensions + config files (go.mod, pyproject.toml, package.json).

2. Enumerate import statements. Grep systematically by language:

   • Python: ^\s*(from|import)\s+
   • TS/JS: ^\s*import\s.*from|^\s*const\s.*require\(
   • Go: ^import\s*\(|^\s*" (inside import ( ... ) blocks)
   • Java: ^import\s+

3. Build file-level edges. source_file → target_symbol pairs.

4. Collapse to module-level edges. Group by top-level package/directory.

5. Detect cycles. Tarjan/Kosaraju over the module graph. Record each SCC with >1 node as a cycle.

6. Identify hubs. Modules with fan-in or fan-out above configurable thresholds (defaults: fan-in >= 8, fan-out >= 8).

7. Emit dependency-graph.yaml:

   project_root: "{project_root}"
   generated_at: "{ISO-8601}"
   languages: [ ... ]
   modules:
     - id: "{module-path}"
       files: {count}
       fan_in: {n}
       fan_out: {n}
   edges:
     - from: "{module}"
       to: "{module}"
       weight: {count of file-level edges}
   cycles:
     - modules: [ "...",  ]
        {}
   
       
        {}
        {}
            
   

Output

dependency_graph_yaml_path: "{output_base}/dependency-graph.yaml"
dependency_graph_md_path: "{output_base}/dependency-graph.md"
module_count: {n}
edge_count: {n}
cycle_count: {n}
status: written

Boundaries

• Read-only.
• Module-level aggregation — do not emit per-file edges in the YAML (too noisy); keep them only in internal computation.
• Mermaid diagrams in the .md must remain renderable — cap at ~60 nodes; for larger codebases split by top-level package.