version: "1.0.1" 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):

``bash python3 "$GRAPH_QUERY" --action communities ``

Fallback (no gauntlet): Analyze directory structure and cross-directory imports: ```bash # 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:

``mermaid 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.

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