code-communities

Code Community Detection

Identify architectural clusters and module boundaries

in the codebase.

When NOT To Use

• One module's imports (use cartograph:dependency-graph)
• Rendering an architecture already decided (use

cartograph:architecture-diagram)

Prerequisites

This skill requires the gauntlet plugin for graph

data. Discover it:

GRAPH_QUERY=$(find ~/.claude/plugins -name "graph_query.py" -path "*/gauntlet/*" 2>/dev/null | head -1)

If gauntlet is not installed: Fall back to directory

structure analysis. Group files by directory and use

import statements to identify module boundaries. Generate

a Mermaid diagram from directory-level relationships.

If installed but no graph.db: Tell the user to run

/gauntlet-graph build.

Steps

1. Run community detection (requires gauntlet):

   python3 "$GRAPH_QUERY" --action communities

Fallback (no gauntlet): Analyze directory structure

and cross-directory imports:

   # Directory-level grouping
   find . -name "*.py" -not -path "*/node_modules/*" | \
       sed 's|/[^/]*$||' | sort | uniq -c | sort -rn

   # Cross-directory imports (rg preferred, grep fallback)
   if command -v rg &>/dev/null; then
     rg "^from |^import " --type py -l . | \
       xargs -I{} rg "^from \w+ import|^import \w+" {} --no-filename
   else
     grep -rh "^from \|^import " --include="*.py" .
   fi | sort | uniq -c | sort -rn | head -20

Group by top-level directories and count cross-directory

imports to estimate coupling.

1. Display clusters:

   Community         | Nodes | Cohesion | Description
   auth              |    12 |    0.85  | Authentication module
   db                |     8 |    0.92  | Database access layer
   api/handlers      |    15 |    0.71  | API request handlers
   utils             |     6 |    0.45  | Shared utilities

1. Show coupling warnings: If communities have

>10 cross-boundary edges, highlight them:

   WARNING: High coupling between 'auth' and 'api/handlers'
   (23 cross-community edges, severity: high)

1. Generate Mermaid diagram:

   flowchart TB
     subgraph auth[Auth Module - cohesion 0.85]
       verify_token
       check_permissions
     end
     subgraph db[DB Layer - cohesion 0.92]
       execute_query
       connection_pool
     end
     auth -->|"23 edges"| api
     db -->|"5 edges"| api

1. Suggest improvements:

• Low cohesion (<0.5): "Consider splitting this

module into more focused components"

• High coupling (>20 edges): "Consider introducing

an interface to reduce direct dependencies"

Algorithm

Uses the Leiden algorithm (when igraph is available)

with edge-type-specific weights. Falls back to

file-based grouping otherwise.

| Edge Type | Weight |

|-----------|--------|

| CALLS | 1.0 |

| INHERITS | 0.8 |

| IMPLEMENTS | 0.7 |

| IMPORTS_FROM | 0.5 |

| TESTED_BY | 0.4 |

| CONTAINS | 0.3 |

Exit Criteria

• [ ] Community table rendered with columns Community, Nodes, Cohesion,

and Description for each detected cluster

• [ ] Coupling warning surfaced for any pair of communities with more

than 10 cross-boundary edges, labelled with severity

• [ ] Mermaid flowchart TB generated with one subgraph per community

showing cohesion score in the subgraph label

• [ ] Improvement suggestions provided for any community with cohesion

< 0.5 or coupling > 20 cross-community edges

• [ ] If gauntlet is not installed, directory-structure fallback runs and

absence of graph data is stated to the user