Skip to main content
D

supergraph

datit309/supergraph

Engineering workflow system for AI coding agents — mandatory planning, TDD, verification, review, and intelligent codebase graph analysis.

Install

dsh plugin --profile web add github:datit309/supergraph

README

Supergraph for AI Coding Agents

Tiếng Việt

Turn AI coding agents from code generators into engineering workflow systems.

SuperGraph doesn't make your coding agent smarter. It makes your coding agent 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.

What the plugin does

Supergraph is a workflow system for AI coding agents, not just a collection of prompts. Every non-trivial change follows:

scan → analyze → plan → TDD → execute → fix → verify → review

The graph layer is powered by Codebase Memory MCP (>= 0.10.8,<0.11.0). It indexes the repository locally under a stable project identity, then provides evidence for blast radius, callers/callees, architecture clusters, dependency cycles, test gaps, complexity hotspots, and changed symbols. Serena is optional and adds LSP-level references and diagnostics.

The workflow is evidence-gated: no production change without a verified RED test, no plan execution without an approved plan, and no completion claim without fresh verification and independent review. Hooks provide session reminders, plan guards, failure hints, and asynchronous graph freshness through Codebase Memory auto-watch.

Windows hook behavior

On Windows, hooks/run-hook.cmd resolves Git Bash dynamically: CLAUDE_CODE_GIT_BASH_PATH, system Git, user-level Git, then where git.exe. This supports Git for Windows installed by winget without administrator rights. If Git Bash is unavailable, hooks print supergraph: Git Bash not found — hooks skipped and exit successfully because hooks are non-blocking; skills and MCP remain usable.

Version License Privacy


Why Supergraph

Without SupergraphWith Supergraph
Claude guesses which files are affectedGraph shows exact blast radius before first keystroke
TDD is optionalRED 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 afterthoughtIndependent reviewer agent + graph cross-check before every merge
Context lost between sessionsHandoff skill compacts full session state in seconds
Refactors break hidden callersSerena LSP finds every reference before rename runs

Supported Platforms

PlatformInstall pathProject memory
Claude CodeMarketplace or local pluginCLAUDE.md
Antigravity CLILocal installerAGENTS.md
Codex CLIMarketplace or local installerAGENTS.md
OpenCodeLocal installerOPENCODE.md

Antigravity and Codex use AGENTS.md; OpenCode uses OPENCODE.md. No CLAUDE.md is required for those platforms. Antigravity hook environment variables and event names are best-effort until verified against a real install.


Prerequisites

DependencyRequiredInstall
Claude Code, Antigravity CLI, Codex CLI, or OpenCode✅ YesSee your platform docs
Python 3.10+✅ Yesbrew install python / apt install python3
codebase-memory-mcp✅ Yespip install 'codebase-memory-mcp>=0.10.8,<0.11.0'
uvOptionalbrew install uv
Serena MCPOptionalSee Serena Setup
Git✅ YesAlready installed on most systems

Installation

One-command local installer

macOS, Linux, or WSL (defaults to all platforms):

curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh

Windows PowerShell 5.1+:

irm https://raw.githubusercontent.com/datit309/supergraph/master/install.ps1 | iex

To install for a single platform explicitly on macOS, Linux, or WSL:

# Claude Code
curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform claude
# Antigravity
curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform antigravity
# Codex
curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform codex
# OpenCode
curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform opencode
# DeepSeek Harness (DSH)
curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform dsh
# All platforms at once
curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform all

The Git checkout lives at ${XDG_DATA_HOME:-$HOME/.local/share}/supergraph on POSIX systems and %LOCALAPPDATA%\supergraph on Windows. Re-running the command performs git pull --ff-only; an uncommitted or diverged checkout is never overwritten. The manual clone instructions below remain available for development and auditing.

Security: inspect both installer scripts before piping remote code into a shell. For example, download the file, review it, then run it locally.

Automatic update notifications

Supergraph checks for a newer stable version at SessionStart, at most once every 24 hours. The check times out after 2 seconds, uses a local cache, and never blocks startup. When an update exists, the notice shows the installed/latest versions and the matching command:

Claude Code: /plugin marketplace update supergraph
Codex: codex plugin marketplace upgrade supergraph
Antigravity: curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform antigravity
OpenCode: curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform opencode
DSH: dsh plugin --profile web update supergraph

Set SUPERGRAPH_UPDATE_CHECK=false to disable the check. OpenCode does not currently expose a SessionStart hook, so its update command is available here but its notification is not automatic.

Option 1 — Claude Code

# Install from Git marketplace (recommended)
/plugin marketplace add https://github.com/datit309/supergraph.git
/plugin install supergraph

# Or install from a local checkout
git clone https://github.com/datit309/supergraph.git
/plugin marketplace add ./supergraph
/plugin install supergraph

# MCP setup
pip install 'codebase-memory-mcp>=0.10.8,<0.11.0'

# First run
/supergraph:scan

# Update later
/plugin marketplace update supergraph

Option 2 — Antigravity CLI

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

# Install plugin files for Antigravity
plugins/supergraph/install.sh --platform antigravity

# MCP setup
pip install 'codebase-memory-mcp>=0.10.8,<0.11.0'

# First run
/supergraph:scan

Uses AGENTS.md for project instructions; no CLAUDE.md required.

Option 3 — Codex CLI

# Add marketplace + install plugin (recommended)
codex plugin marketplace add datit309/supergraph
codex plugin add supergraph@supergraph

# Or manual install from a local checkout
git clone https://github.com/datit309/supergraph.git
cd supergraph
plugins/supergraph/install.sh --platform codex

# MCP setup
pip install 'codebase-memory-mcp>=0.10.8,<0.11.0'

# First run
/supergraph:scan

# Update later
codex plugin marketplace upgrade supergraph

Uses AGENTS.md for project instructions; no CLAUDE.md required.

Option 4 — OpenCode

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

# Symlink skills + print opencode.json config snippet
plugins/supergraph/install.sh --platform opencode

# MCP setup
pip install 'codebase-memory-mcp>=0.10.8,<0.11.0'

# First run
/supergraph:scan

The installer symlinks each skill folder into ~/.config/opencode/skills/<name> (global), copies OPENCODE.md to ~/.config/opencode/, and creates/prints ~/.config/opencode/opencode.json:

{
  "instructions": ["OPENCODE.md"],
  "mcp": {
    "codebase-memory-mcp": { "type": "stdio", "command": "codebase-memory-mcp", "args": [] },
    "serena": { "type": "stdio", "command": "serena", "args": ["start-mcp-server", "--context=opencode", "--project-from-cwd"] }
  }
}

OpenCode uses OPENCODE.md for project instructions. Skills and MCP work out of the box. Hooks (SessionStart, caveman, etc.) are not available on OpenCode — the platform uses a JS/TS plugin model instead of bash hooks.

Invoking skills on OpenCode: use /skills, then choose scan, plan, tdd, etc. Do not use /supergraph:* in OpenCode.

Option 5 — DeepSeek Harness (DSH)

Supergraph supports standard Cordis Plugin & Bundle integration for DeepSeek Harness:

Via DSH Plugin Manager CLI:

# Add Supergraph bundle to your active profile (e.g. web, headless):
dsh plugin --profile web add github:datit309/supergraph

# Or from a local checkout:
dsh plugin --profile web add /path/to/supergraph

Or via the DSH Web GUI (http://127.0.0.1:3080):

  1. Open Settings → Plugins (or open the Plugins drawer in the sidebar).
  2. Under Install Bundle, enter github:datit309/supergraph (or your local path).
  3. Click Install. The plugin activates immediately via HMR without requiring a restart.

The Plugin Bundle automatically:

  • Registers all 38 skills via ctx.skills.registerProvider().
  • Configures codebase-memory and serena MCP servers via @deepseek-ai/dsh-mcp-client.
  • Injects workflow rules from AGENTS.md into ctx.systemPrompt.
git clone https://github.com/datit309/supergraph.git
cd supergraph

# Symlink skills to ~/.dsh/skills + configure MCP in ~/.dsh/cordis.patch.yml
plugins/supergraph/install.sh --platform dsh

# Or via one-liner:
curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform dsh

Invoking skills on DSH: Skills are registered with bare kebab-case names according to DSH standards (/^[a-z0-9]+(?:-[a-z0-9]+)*$/).

  • Slash commands: /scan, /plan, /tdd, /verify, /review, etc. Do not use /supergraph:* in DSH.
  • Tool call: skill(name="scan"), skill(name="plan"), etc.
  • Agent Preset: Bundles dedicated Supergraph Engineer Agent Preset with graph-first navigation, TDD rules, and strict tool-result log pruning. Select directly from DSH Web preset menu.

MCP Setup

Codebase Memory MCP >= 0.10.8,<0.11.0 (required)

pip install 'codebase-memory-mcp>=0.10.8,<0.11.0'
codebase-memory-mcp --version
codebase-memory-mcp cli index_repository --repo-path "$(pwd)" --name supergraph --mode moderate

/supergraph:scan registers or builds the graph on first run and records CBM_PROJECT in .supergraph-env. Codebase Memory auto_watch=true keeps the local index fresh asynchronously; quality gates explicitly check index status and reindex before impact analysis.

Serena Setup

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

# 1. Install uv (if not already installed)
brew install uv   # macOS
# or: curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install Serena
uv tool install -p 3.13 serena-agent

The plugin's .mcp.json already registers Serena with Claude Code — no extra setup needed.

Verify: run /mcp in Claude Code and confirm serena appears.

All supergraph skills use Serena automatically when available.


Quick Start

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

# 2. Analyze — frames the problem, scores risk, proposes approach
#    (includes ambiguity grilling + 5-persona debate → GO/CAUTION/STOP)
/supergraph:analyze

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

# 4. Implement with TDD
/supergraph:tdd

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

# 6. Verify before claiming done
/supergraph:verify

# 7. Review before merge
/supergraph:review

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

Ambiguous requirements or touching hub/bridge nodes? Start with /supergraph:analyze — it handles grilling, risk scoring, and approach selection before you plan.


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

SkillPurposeWhen to use
/supergraph:scanLoad graph, detect project language, save envFirst thing every session
/supergraph:analyzeRisk analysis + structured grill + approach selectionAmbiguous scope, hub/bridge nodes involved
/supergraph:planGraph scan, blast radius, task breakdown with TDD mappingBefore writing any non-trivial code
/supergraph:executeDispatch saved plan, orchestrate parallel/sequential tasksPlan is saved and approved
/supergraph:tddRED → GREEN → REFACTOR per taskImplementing any feature or fix
/supergraph:fixAuto-fix loop: test + lint + format + graph checkAfter all coding, before claiming done
/supergraph:integrationRun integration and e2e testsAfter unit tests pass
/supergraph:verifyFresh evidence gate — no claims without proofBefore done/ready/commit
/supergraph:reviewIndependent code reviewer agent + graph cross-checkBefore merge or PR

Debugging & Investigation

SkillPurposeWhen to use
/supergraph:diagnose6-phase debug: reproduce → hypothesize → instrument → fixBug exists, cause unknown
/supergraph:zoom-outOne-shot domain-vocabulary module mapLost in unfamiliar code, need re-orientation
/supergraph:architectureHTML + Mermaid architecture review reportPre-refactor, onboarding, architectural planning

Planning & Requirements

SkillPurposeWhen to use
/supergraph:prdConvert conversation → structured PRD + GitHub IssueRequirements came from discussion
/supergraph:triageIssue state machine → ready-for-agent / needs-info / wontfixProcessing backlog
/supergraph:prototypeThrowaway code to validate approachUncertain approach before planning

Session & Productivity

SkillPurposeWhen to use
/supergraph:handoffCompact session state to file for next sessionContext window exhausted, switching sessions
/supergraph:caveman~75% token compression modeLong session, tight token budget

Domain-Specific

SkillPurposeWhen to use
/supergraph:serenaLSP setup, tool reference, symbol navigationComplex refactors, cross-file analysis
/supergraph:database-migrationsSchema changes, rollbacks, zero-downtime patternsAny DB migration work
/supergraph:flutter-uiBuild Flutter UI from Figma MCP or image — scans design tokens, never hard-codesFlutter UI from Figma or screenshot
/supergraph:flutter-dart-code-review15-section Flutter/Dart review checklistFlutter/Dart code review
/supergraph:frontend-designProduction-grade UI — no generic AI aestheticsWeb UI components and layouts
/supergraph:webapp-testingPlaywright-based web application testingE2E web testing

Smart Hooks

Skills are invoked manually. Hooks inject smart context automatically based on observable signals.

HookFires whenWhat it does
SessionStartEvery sessionLoads CONTEXT.md vocabulary; reminds about recent handoff; activates caveman if flagged; suggests zoom-out when no plan exists
UserPromptSubmitEvery messageDetects caveman trigger phrases → activates compression; detects triage keywords → suggests triage
PostToolUse BashAfter Bash runsDetects test failure patterns → injects /supergraph:diagnose suggestion
PreCompactBefore context compactionFires urgent handoff reminder with active plan task counts
PreToolUse Write/EditBefore writing source filesChecks plan exists and is approved
PostToolUse Write/EditAfter writing source filesCodebase Memory auto_watch=true refreshes asynchronously
StopWhen Claude stopsReports plan progress + uncommitted changes

Activate caveman permanently (persists across sessions):

echo "SUPERGRAPH_CAVEMAN=true" >> .supergraph-env

Example Use Cases

1. Adding a feature to a heavily-coupled service

"Add payment webhook handling to our API"

Scan detects PaymentService is a hub node connected to 14 modules. Plan shows blast radius before you write a line. TDD enforces a failing test first. Review catches the circular dependency before it ships.


2. Debugging a flaky CI test

"Tests fail on CI but pass locally"

/supergraph:diagnose — 6-phase structured loop: reproduces the failure, maps involved files via graph traversal, checks for race conditions and env differences, proposes a targeted fix with evidence.


3. Safe large-scale refactor

"Rename UserService to AccountService across the codebase"

Serena's rename_symbol + graph impact analysis shows every caller, test, and interface implementation before the rename runs. Zero broken imports.


4. Onboarding to an unfamiliar codebase

"I just joined this project. Where do I start?"

/supergraph:zoom-out generates a domain-vocabulary module map in seconds. /supergraph:architecture produces an HTML + Mermaid report you can share with the team.


5. Processing a messy issue backlog

"We have 40 open issues. Which ones can we actually ship?"

/supergraph:triage classifies each issue through a formal state machine — ready-for-agent, needs-info, or wontfix — with reasoning. Turns backlog chaos into a sprint queue.


6. Context window running out mid-task

"Been coding for 2 hours, context is getting long"

/supergraph:handoff compresses full session state — active plan tasks, uncommitted changes, decisions made, next steps — into a compact file. Resume in a fresh session in under 30 seconds.


7. Zero-downtime database migration

"Add a NOT NULL column to a 2M-row users table"

/supergraph:database-migrations guides the expand-contract pattern: add nullable → backfill → add constraint → drop old column. Rollback scripts at every step, zero-downtime strategies per your ORM.


Supported Languages

Auto-detected from config files at session start:

Config fileStackTestLintFormat
pubspec.yamlFlutter / Dartflutter testflutter analyzedart format
package.jsonNode.js / TypeScriptjest, vitest, mochaeslintprettier
composer.jsonPHPphpunit, pestphpstanphp-cs-fixer
pyproject.toml / setup.pyPythonpytestruffruff format
go.modGogo testgolangci-lintgofmt
Cargo.tomlRustcargo testcargo clippycargo fmt

Team Setup

1. Install the plugin

/plugin marketplace add https://github.com/datit309/supergraph.git
/plugin install supergraph

2. Install MCP dependencies

pip install 'codebase-memory-mcp>=0.10.8,<0.11.0' # required
uv tool install -p 3.13 serena-agent           # optional — see Serena Setup above

3. Start working

Open any project in Claude Code and run:

/supergraph:scan

First run builds the graph automatically. That's it.


Optional: Share workflow with your team

Commit these files to your project repo so every team member gets the same setup automatically when they clone:

.mcp.json — declares the MCP servers:

{
  "mcpServers": {
    "codebase-memory-mcp": { "command": "codebase-memory-mcp", "args": [] },
    "serena": {
      "command": "serena",
      "args": [
        "start-mcp-server",
        "--context=claude-code",
        "--project-from-cwd"
      ]
    }
  }
}

CLAUDE.md — copy from the installed plugin's CLAUDE.md as a starting point, then customize for your project.

.githooks/pre-commit — run tests/lint on every commit:

mkdir -p .githooks
# copy content from: ~/.claude/plugins/cache/supergraph/supergraph/<version>/.githooks/pre-commit
chmod +x .githooks/pre-commit
git config core.hooksPath .githooks

Add to .gitignore:

.claude/settings.local.json
.supergraph-env

What gets committed vs. what stays local

PathCommit?Why
.mcp.json✅ YesMCP server config — team needs same MCPs
CLAUDE.md✅ YesProject-level workflow instructions
.codebase-memory/graph.db.zstOptionalCompressed team bootstrap artifact; local index is in ~/.cache/codebase-memory-mcp
docs/supergraph/plans/✅ YesPlans are contracts — visible to whole team
.github/✅ YesPR templates, CI workflows, issue templates
.githooks/pre-commit✅ YesShared commit quality gate
.supergraph-env⚠️ OptionalContains personal flags like CAVEMAN — gitignore if personal
.claude/settings.local.json❌ NoPersonal tool permissions

See docs/TEAM-SETUP.md for CI/CD pipelines, pre-commit hooks, PR templates, and full onboarding guide.


Hard Rules

These rules are enforced by the skill chain and hooks — not optional:

  1. Never write code without a plan (skip only for trivial changes: <10 lines, 1 file)
  2. Never implement without a failing test — TDD is mandatory
  3. Never read entire codebase — use graph blast radius instead
  4. Never modify hub nodes without explicit user approval
  5. Never skip the auto-fix loop after coding
  6. Never commit if tests fail or review returns CRITICAL
  7. Always use graph MCP tools before assuming file relationships
  8. Always detect language before running test/lint commands
  9. Always read the skill file before executing each phase
  10. Always save plans to docs/supergraph/plans/ for multi-session work

Escalation Table

ConditionAction
TDD fails 3 times on the same taskMark stuck, skip, continue next task
Fix loop fails 3 iterationsSTOP — report issues — never commit broken
Review returns NEEDS_CHANGESReturn to fix (max 2 review cycles)
Review returns BLOCKEDEscalate to human immediately
Blast radius > 20 filesSTOP — discuss with user before proceeding
Hub node modificationRequire explicit user approval
Surprise score > 0.7Require investigation and justification
New circular dependency detectedBlock — fix before merge

Project Structure

plugins/supergraph/
├── .claude-plugin/
│   └── marketplace.json        # Plugin manifest (v2.2.0)
├── skills/
│   ├── scan/                   # Context loading & graph build
│   ├── analyze/                # Risk analysis + grill + approach selection
│   ├── plan/                   # Graph-informed plan creation
│   ├── execute/                # Plan dispatch & orchestration
│   ├── tdd/                    # RED → GREEN → REFACTOR per task
│   ├── fix/                    # Auto-fix loop (test + lint + graph)
│   ├── integration/            # E2E / integration tests
│   ├── verify/                 # Verification gate
│   ├── review/                 # Final graph-aware review
│   ├── diagnose/               # 6-phase structured debugging
│   ├── zoom-out/               # One-shot domain module map
│   ├── architecture/           # HTML + Mermaid architecture review
│   ├── prd/                    # PRD generation → GitHub Issues
│   ├── triage/                 # Issue state machine
│   ├── prototype/              # Throwaway Logic/UI validation
│   ├── handoff/                # Session compaction
│   ├── caveman/                # Token-compression mode
│   ├── serena/                 # Serena LSP integration
│   ├── database-migrations/    # DB migration patterns
│   ├── flutter-ui/             # Flutter UI from Figma/image
│   ├── flutter-dart-code-review/ # Flutter/Dart review checklist
│   ├── frontend-design/        # Production-grade UI
│   └── webapp-testing/         # Playwright web testing
├── agents/
│   ├── plan-writer.md          # Creates plans, never writes code
│   ├── plan-reviewer.md        # Reviews plans pre-execution
│   ├── executor.md             # Executes plans, never creates them
│   └── code-reviewer.md        # Final independent review agent
├── hooks/
│   ├── session-start           # CONTEXT.md load, handoff reminder
│   ├── user-prompt-submit      # Caveman activation, triage hint
│   ├── post-tool-use-bash      # Test failure detection
│   ├── pre-compact             # Handoff reminder before compaction
│   ├── pre-tool-use            # Plan existence guard
│   ├── post-tool-use           # Auto graph update after writes
│   ├── stop                    # Plan progress report
│   └── hooks.json              # Event → script mapping
├── docs/
│   └── TEAM-SETUP.md           # Team onboarding guide
├── PRIVACY.md                  # Privacy policy
├── CHANGELOG.md                # Version history
├── CLAUDE.md                   # Engineering principles
└── settings.json               # Permissions + allowed commands

Privacy

Supergraph is local-first — no remote servers, no telemetry, no code uploaded anywhere.

All graph analysis runs locally. Codebase Memory stores its index in ~/.cache/codebase-memory-mcp; teams may optionally share .codebase-memory/graph.db.zst. Serena also runs locally.

See PRIVACY.md for the full policy.


Changelog

See CHANGELOG.md for full version history.

Current: v2.2.4 — Migrated graph intelligence to Codebase Memory MCP, added project/index lifecycle checks, and fixed Windows hooks for system/user-level Git Bash installations.

v2.2.0 — Added 8 new skills (diagnose, handoff, triage, caveman, prd, architecture, prototype, zoom-out), CONTEXT.md shared vocabulary system, 4 smart automation hooks.


License

MIT — see LICENSE for details.


Related plugins