leo-claude-mktplace/plugins/contract-validator/commands/dependency-graph.md

/dependency-graph - Generate Dependency Visualization

Visual Output

When executing this command, display the plugin header:

┌──────────────────────────────────────────────────────────────────┐
│  ✅ CONTRACT-VALIDATOR · Dependency Graph                         │
└──────────────────────────────────────────────────────────────────┘

Then proceed with the visualization.

Generate a Mermaid flowchart showing plugin dependencies, data flows, and tool relationships.

Usage

/dependency-graph [marketplace_path] [--format <mermaid|text>] [--show-tools]

Parameters

• marketplace_path (optional): Path to marketplace root. Defaults to current project root.
• --format (optional): Output format - mermaid (default) or text
• --show-tools (optional): Include individual tool nodes in the graph

Workflow

1. Discover plugins:

   • Scan plugins directory for all plugins with .claude-plugin/ marker
   • Parse each plugin's README.md to extract interface
   • Parse CLAUDE.md for agent definitions and tool sequences

2. Analyze dependencies:

   • Identify shared MCP servers (plugins using same server)
   • Detect tool dependencies (which plugins produce vs consume data)
   • Find agent tool references across plugins
   • Categorize as required (ERROR if missing) or optional (WARNING if missing)

3. Build dependency graph:

   • Create nodes for each plugin
   • Create edges for:
     • Shared MCP servers (bidirectional)
     • Data producers -> consumers (directional)
     • Agent tool dependencies (directional)
   • Mark edges as optional or required

4. Generate Mermaid output:

   • Create flowchart diagram syntax
   • Style required dependencies with solid lines
   • Style optional dependencies with dashed lines
   • Group by MCP server or data flow

Output Format

Mermaid (default)

flowchart TD
    subgraph mcp_gitea["MCP: gitea"]
        projman["projman"]
        pr-review["pr-review"]
    end

    subgraph mcp_data["MCP: data-platform"]
        data-platform["data-platform"]
    end

    subgraph mcp_viz["MCP: viz-platform"]
        viz-platform["viz-platform"]
    end

    %% Data flow dependencies
    data-platform -->|"data_ref (required)"| viz-platform

    %% Optional dependencies
    projman -.->|"lessons (optional)"| pr-review

    %% Styling
    classDef required stroke:#e74c3c,stroke-width:2px
    classDef optional stroke:#f39c12,stroke-dasharray:5 5

Text Format

DEPENDENCY GRAPH
================

Plugins: 12
MCP Servers: 4
Dependencies: 8 (5 required, 3 optional)

MCP Server Groups:
  gitea: projman, pr-review
  data-platform: data-platform
  viz-platform: viz-platform
  netbox: cmdb-assistant

Data Flow Dependencies:
  data-platform -> viz-platform (data_ref) [REQUIRED]
  data-platform -> data-platform (data_ref) [INTERNAL]

Cross-Plugin Tool Usage:
  projman.Planner uses: create_issue, search_lessons
  pr-review.reviewer uses: get_pr_diff, create_pr_review

Dependency Types

Type	Line Style	Meaning
Required	Solid (-->)	Plugin cannot function without this dependency
Optional	Dashed (-.->)	Plugin works but with reduced functionality
Internal	Dotted (...>)	Self-dependency within same plugin
Shared MCP	Double (==>)	Plugins share same MCP server instance

Known Data Flow Patterns

The command recognizes these producer/consumer relationships:

Data Producers

• read_csv, read_parquet, read_json - File loaders
• pg_query, pg_execute - Database queries
• filter, select, groupby, join - Transformations

Data Consumers

• describe, head, tail - Data inspection
• to_csv, to_parquet - File writers
• chart_create - Visualization

Cross-Plugin Flows

• data-platform produces data_ref -> viz-platform consumes for charts
• projman produces issues -> pr-review references in reviews
• gitea wiki -> projman lessons learned

Examples

Basic Usage

/dependency-graph

Generates Mermaid diagram for current marketplace.

With Tool Details

/dependency-graph --show-tools

Includes individual tool nodes showing which tools each plugin provides.

Text Summary

/dependency-graph --format text

Outputs text-based summary suitable for CLAUDE.md inclusion.

Specific Path

/dependency-graph ~/claude-plugins-work

Analyze marketplace at specified path.

Integration with Other Commands

Use with /validate-contracts to:

1. Run /dependency-graph to visualize relationships
2. Run /validate-contracts to find issues in those relationships
3. Fix issues and regenerate graph to verify

Available Tools

Use these MCP tools:

• parse_plugin_interface - Extract interface from plugin README.md
• parse_claude_md_agents - Extract agents and their tool sequences
• generate_compatibility_report - Get full interface data (JSON format for analysis)
• validate_data_flow - Verify data producer/consumer relationships

Implementation Notes

Detecting Shared MCP Servers

Check each plugin's .mcp.json file for server definitions:

# List all .mcp.json files in plugins
find plugins/ -name ".mcp.json" -exec cat {} \;

Plugins with identical MCP server names share that server.

Identifying Data Flows

1. Parse tool categories from README.md
2. Map known producer tools to their output types
3. Map known consumer tools to their input requirements
4. Create edges where outputs match inputs

Optional vs Required

• Required: Consumer tool has no default/fallback behavior
• Optional: Consumer works without producer (e.g., lessons search returns empty)

Determination is based on:

• Issue severity from validate_data_flow (ERROR = required, WARNING = optional)
• Tool documentation stating "requires" vs "uses if available"

Sample Output

For the leo-claude-mktplace:

flowchart TD
    subgraph gitea_mcp["Shared MCP: gitea"]
        projman["projman<br/>14 commands"]
        pr-review["pr-review<br/>6 commands"]
    end

    subgraph netbox_mcp["Shared MCP: netbox"]
        cmdb-assistant["cmdb-assistant<br/>3 commands"]
    end

    subgraph data_mcp["Shared MCP: data-platform"]
        data-platform["data-platform<br/>7 commands"]
    end

    subgraph viz_mcp["Shared MCP: viz-platform"]
        viz-platform["viz-platform<br/>7 commands"]
    end

    subgraph standalone["Standalone Plugins"]
        doc-guardian["doc-guardian"]
        code-sentinel["code-sentinel"]
        clarity-assist["clarity-assist"]
        git-flow["git-flow"]
        claude-config-maintainer["claude-config-maintainer"]
        contract-validator["contract-validator"]
    end

    %% Data flow: data-platform -> viz-platform
    data-platform -->|"data_ref"| viz-platform

    %% Cross-plugin: projman lessons -> pr-review context
    projman -.->|"lessons"| pr-review

    %% Styling
    classDef mcpGroup fill:#e8f4fd,stroke:#2196f3
    classDef standalone fill:#f5f5f5,stroke:#9e9e9e
    classDef required stroke:#e74c3c,stroke-width:2px
    classDef optional stroke:#f39c12,stroke-dasharray:5 5

    class gitea_mcp,netbox_mcp,data_mcp,viz_mcp mcpGroup
    class standalone standalone