supergraph

Supergraph for Claude Code

Tiếng Việt

Turn Claude Code from a code generator into an engineering workflow system.

SuperGraph doesn't make Claude Code smarter. It makes Claude Code behave like a disciplined engineer.

SuperGraph enforces planning, TDD, verification, review, and architecture-aware decision making through mandatory workflows, graph intelligence, and LSP-powered code analysis.

---

Why Supergraph

Without Supergraph	With Supergraph
Claude guesses which files are affected	Graph shows exact blast radius before first keystroke
TDD is optional	RED test is mandatory — no production code without a failing test
"It works on my machine"	6-phase diagnose loop with deterministic feedback
Review is an afterthought	Independent reviewer agent + graph cross-check before every merge
Context lost between sessions	Handoff skill compacts full session state in seconds
Refactors break hidden callers	Serena LSP finds every reference before rename runs

---

Prerequisites

Dependency	Required	Install
Claude Code CLI	✅ Yes	See Claude Code docs
Python 3.10+	✅ Yes	brew install python / apt install python3
code-review-graph	✅ Yes	pip install code-review-graph
Serena MCP	Optional	See Serena Setup
Git	✅ Yes	Already installed on most systems

---

Installation

Option 1 — Git Marketplace (Recommended)

# Add plugin marketplace from Git repo
/plugin marketplace add https://github.com/datit309/supergraph.git

# Install the plugin
/plugin install supergraph

# Update later
/plugin marketplace update supergraph

Option 2 — Local Directory

git clone https://github.com/datit309/supergraph.git

/plugin marketplace add ./supergraph
/plugin install supergraph

---

Graph Setup

The codebase graph must be built once per project. It powers blast radius analysis, hub node detection, and community boundaries.

# Install the graph tool
pip install code-review-graph

# Register the MCP server in your project
code-review-graph install

# Build the initial graph index
code-review-graph build

Verify the graph is healthy:

code-review-graph status

The graph updates automatically after every file write (via PostToolUse hook). Rebuild manually after large merges:

code-review-graph build

---

Serena Setup

Serena adds LSP-level intelligence: find all callers, safe cross-codebase rename, type diagnostics. Optional but recommended for complex refactors.

# Install Serena MCP server
pip install serena

# Add to your project's .mcp.json
serena install

Once installed, all supergraph skills automatically use Serena tools where available (find_referencing_symbols, get_diagnostics_for_file, rename_symbol, etc.).

---

Quick Start

# 1. Start a session — always run scan first
/supergraph:scan

# 2. Plan before any non-trivial change
/supergraph:plan

# 3. Implement with TDD
/supergraph:tdd

# 4. Auto-fix after coding
/supergraph:fix

# 5. Verify before claiming done
/supergraph:verify

# 6. Review before merge
/supergraph:review

Small change (1-2 files, <10 lines)? Skip plan → /supergraph:tdd → /supergraph:fix → /supergraph:review

---

Workflow

SESSION START
  → /supergraph:scan
  → Load graph, detect language, save .supergraph-env
         │
         ▼
PLANNING PHASE
  → /supergraph:analyze   (ambiguous scope, hub/bridge nodes)
  → /supergraph:plan      (blast radius, task breakdown, user approval)
  → Save to docs/supergraph/plans/YYYY-MM-DD-*.md
         │
    ┌────┴────────────────────┐
    ▼                         ▼
SMALL CHANGE              LARGE CHANGE
1-2 files, <10 lines      Multi-file, complex
/supergraph:tdd           /supergraph:execute
    │                         │ (parallel tasks)
    └────────┬────────────────┘
             ▼
  Per task: RED → GREEN → REFACTOR → commit
             │
             ▼
  /supergraph:fix
  Tests + lint + format + graph (max 3 iterations)
             │
             ▼
  /supergraph:integration   (if e2e configured)
             │
             ▼
  /supergraph:verify        (evidence gate)
             │
             ▼
  /supergraph:review        (graph-aware, independent agent)
  → APPROVED / NEEDS_CHANGES / BLOCKED

---

Skills

All skills use the /supergraph: prefix to avoid conflicts with built-in commands.

Core Workflow