pactkit-visualize

name	pactkit-visualize
description	Generate project code dependency graph (Mermaid), supporting file-level, class-level, function-level, and module-level analysis
model	haiku

PactKit Visualize

Generate project code relationship graphs (Mermaid format), supporting four analysis modes.

Script location: Use the base directory from the skill invocation header to resolve script paths.

Prerequisites

• The project must have Python source files (.py) to generate meaningful graphs
• The docs/architecture/graphs/ directory is automatically created by init_arch

Command Reference

visualize -- Generate code dependency graph

python3 ${CLAUDE_PLUGIN_ROOT}/skills/pactkit-visualize/scripts/visualize.py visualize [--mode file|class|call|module] [--entry <func>] [--focus <module>]

Parameter	Description	Default
--mode file	File-level dependency graph (inter-module import relationships)	Default
--mode class	Class diagram (including inheritance)	-
--mode call	Function-level call graph	-
--mode module	Module-level dependency graph with weighted cross-module edges	-
--entry <func>	BFS transitive chain tracing from specified function (requires --mode call)	-
--focus <module>	Scope scan to a specific module directory. MUST be an exact module name from the project (e.g., pactkit, app), not a keyword or concept. Run without --focus first to see available modules.	-

init_arch -- Initialize architecture directory

python3 ${CLAUDE_PLUGIN_ROOT}/skills/pactkit-visualize/scripts/visualize.py init_arch

• Creates docs/architecture/graphs/ and docs/architecture/governance/
• Generates placeholder file system_design.mmd

list_rules -- List governance rules

python3 ${CLAUDE_PLUGIN_ROOT}/skills/pactkit-visualize/scripts/visualize.py list_rules

• Outputs the list of rule files under docs/architecture/governance/

Output Files

Mode	Output Path	Mermaid Type
--mode file	docs/architecture/graphs/code_graph.mmd	graph TD
--mode class	docs/architecture/graphs/class_graph.mmd	classDiagram
--mode call	docs/architecture/graphs/call_graph.mmd	graph TD
--mode module	docs/architecture/graphs/module_graph.mmd	graph TD
--focus (file)	docs/architecture/graphs/focus_file_graph.mmd	graph TD
--focus (class)	docs/architecture/graphs/focus_class_graph.mmd	classDiagram
--focus (call)	docs/architecture/graphs/focus_call_graph.mmd	graph TD

Usage Scenarios

• project-plan, project-act, and pactkit-trace use pactkit query --json --explain for analysis.
• Use visualize only to explicitly regenerate derived Mermaid projections.
• pactkit-doctor checks graph-provider health and derived graph status.

Graph Query Protocol

MUST NOT Read a full .mmd graph file — graph files are large (50K–120K, 1000–2000+ lines). Full reads waste tokens before any work begins.

Unified Query Router

pactkit query --callers atomic_write --json --explain
pactkit query --callees deploy --json --explain
pactkit query --chain atomic_write --json --explain
pactkit query --chain deploy --down --json --explain
pactkit query --explore deployer --json --explain
pactkit query --impact deploy --json --explain

The router owns Codegraph health, bounded sync, and provider selection. Configured Codegraph fails closed. Only an explicit --allow-fallback may select builtin_graph and then text_search; a healthy empty result never triggers fallback.