/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