/graphify-integration

name: graphify-integration
description: Graph-aware planning and research using codebase knowledge graphs — enables architecture-aware task decomposition, dependency discovery, and context reduction

Graphify Integration Skill

This skill enables Forge to leverage codebase knowledge graphs for architecture-aware planning and research. When a graphify knowledge graph exists (or can be generated), Forge agents use it to understand code structure, discover dependencies, prioritize tasks, and reduce context size.

Prerequisites

Graphify integration is **optional but recommended** for projects with:

• 20+ source files
• Multiple modules or packages
• Cross-component dependencies
• Unfamiliar codebases (new contributor scenario)

Installation

Graphify is bundled as part of Forge's tool ecosystem. Install via:

pip install graphifyy

Or use `/forge setup-tools` which detects and offers to install graphify automatically.

Detection and Auto-Build

At the start of `/forge plan` or `/forge execute`, the commands auto-detect and build:

# Check if graphify is installed
node scripts/forge-tools.cjs graph-status

# If installed and no graph exists, build one automatically
node scripts/forge-tools.cjs graph-build --project-dir .

# Extract summary for planning context (god nodes, communities, stats)
node scripts/forge-tools.cjs graph-summary --graph graphify-out/graph.json

The build runs `graphify .` which processes the codebase through: detect -> extract (tree-sitter AST) -> build (NetworkX) -> cluster (Leiden) -> analyze -> export. Output goes to `graphify-out/` (graph.json, graph.html, GRAPH_REPORT.md).

Never block on graph availability. If graphify is not installed or the build fails, all commands proceed with standard behavior.

CLI Commands

Agents use these node one-liners to query the graph (no Python needed at query time):

| Command | Purpose | |---------|---------| | `graph-status` | Check if graphify CLI is installed | | `graph-build --project-dir .` | Build knowledge graph from codebase | | `graph-summary --graph graphify-out/graph.json` | Get god nodes, communities, stats | | `graph-query --graph graphify-out/graph.json --term "auth"` | Search for nodes matching a term | | `graph-dependents --graph graphify-out/graph.json --file "src/auth.ts"` | Find all files that depend on a file |

Graph-Enhanced Planning

When a knowledge graph is available, the forge-planner agent gains these capabilities:

1. Architecture-Aware Task Decomposition

Before decomposing specs into tasks, query the graph to understand the codebase structure:

Query: "What are the main architectural components?"
Result: god nodes (highest-connectivity concepts), community clusters

Use this to:

• Align task boundaries with existing module boundaries (communities)
• Identify god nodes (core abstractions) that many tasks will touch -- these need careful ordering
• Detect cross-cutting concerns that affect multiple communities

2. Dependency Discovery

Query the graph to find implicit dependencies not obvious from the spec:

Query: "What depends on {module}?"
Result: downstream consumers, shared utilities, integration points

Use this to:

• Add dependency edges to the task DAG that the spec alone would miss
• Identify tasks that should be in earlier tiers because they affect shared infrastructure
• Flag tasks that touch god nodes as higher risk (more potential blast radius)

3. Task Prioritization by Connectivity

Rank tasks by the connectivity of the code they modify:

• Tasks touching god nodes (high-degree concepts) go in earlier tiers
• Tasks in isolated communities (low cross-cluster edges) can safely run in parallel
• Bridge tasks (connecting two communities) need careful dependency ordering

4. Context Reduction for Executors

Instead of loading the full codebase context for each task, query the graph for the relevant subgraph:

Query: "Show everything related to {task-target} within depth 3"
Result: relevant nodes, edges, and source files

This provides the executor with a focused context window containing only the files and relationships relevant to their task, rather than the entire codebase.

Graph-Enhanced Research

The forge-researcher agent can use the graph to:

1. Pre-Implementation Architecture Scan

Before researching external docs, query the graph to understand what already exists:

Query: "Explain {concept}"
Result: all connections to the concept -- what it depends on, what depends on it, which community it belongs to

2. Impact Analysis

Before implementing a change, query the graph for blast radius:

Query: "Path from {source} to {target}"
Result: shortest path through the dependency graph, revealing hidden coupling

3. Pattern Discovery

Identify how similar patterns are already implemented in the codebase:

Query: "Show nodes similar to {pattern} in community {N}"
Result: related implementations that can serve as templates

Graph-Enhanced Review

The forge-reviewer agent can use the graph to:

1. Blast Radius Verification

Cross-reference modified files against the graph to find all downstream consumers:

Query: "What depends on {modified-file}?"
Result: all files and concepts that consume exports from the modified file

2. Community Boundary Checks

Verify that changes respect architectural boundaries:

Query: "Which community does {file} belong to?"
Result: community assignment, cohesion score, bridge status

If a task modifies files in multiple communities without explicit cross-cutting justification, flag for review.

Integration Points

In forge-planner (planning phase)

1. Load `graphify-out/graph.json` if it exists 2. Extract god nodes and community structure 3. Use community boundaries to inform task grouping 4. Use node connectivity to inform tier ordering 5. Add graph-discovered dependencies to the frontier DAG

In forge-rese