code-communities

name	code-communities
description	Detects architectural clusters and coupling boundaries via community detection on the code graph. Use when identifying module groupings or refactoring targets.

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.

2. 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
   

3. 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)
   

4. 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
   

5. 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