Imported from datit309/supergraph (plugins/supergraph/AGENTS.md). Install upstream with npx skills add datit309/supergraph --skill supergraph. Copyright stays with the author.

Supergraph — Mandatory Workflows

CRITICAL: These are MANDATORY. Not suggestions. Not optional. Every coding task MUST follow this process.

Skills

This project uses supergraph skills:

Claude Code & Codex: invoke with /supergraph: prefix (e.g. /supergraph:scan, /supergraph:plan).
DeepSeek Harness (DSH) & OpenCode: invoke bare skill names without prefix (e.g. /scan, /plan, /tdd, /verify, or via tool skill(name="scan") on DSH). DSH skill names follow /^[a-z0-9]+(?:-[a-z0-9]+)*$/ and do not use colons. Your AI agent MUST read and follow the relevant skill before each phase.

Skill (Claude/Codex)	Skill (DSH/OpenCode)	When to read
`/supergraph:scan`	`/scan`	Start of every session
`/supergraph:analyze`	`/analyze`	Ambiguous scope, touching hub/bridge
`/supergraph:sdd`	`/sdd`	System/Software design, data contracts, API schemas, multi-platform matrix
`/supergraph:plan`	`/plan`	Before writing any code
`/supergraph:tdd`	`/tdd`	When implementing any feature or fix
`/supergraph:execute`	`/execute`	When executing saved plans
`/supergraph:fix`	`/fix`	After all coding is complete
`/supergraph:integration`	`/integration`	After unit tests pass
`/supergraph:verify`	`/verify`	Before claiming done/ready or committing
`/supergraph:review`	`/review`	Before merging or when review is needed
`/supergraph:diagnose`	`/diagnose`	Bug exists and cause is unknown
`/supergraph:serena`	`/serena`	Before complex refactors, cross-file symbol analysis, or type diagnostics
`/supergraph:zoom-out`	`/zoom-out`	Lost in unfamiliar code, need re-orientation
`/supergraph:architecture`	`/architecture`	Pre-refactor, onboarding, architectural planning
`/supergraph:prd`	`/prd`	Requirements came from conversation, not a formal spec
`/supergraph:triage`	`/triage`	Processing issue backlog, preparing work for automation
`/supergraph:prototype`	`/prototype`	Approach is uncertain before planning
`/supergraph:handoff`	`/handoff`	Agent context window exhausted or switching sessions
`/supergraph:caveman`	`/caveman`	Long session or token budget — activate compression

Auto Language Detection

At session start, detect project type:

pubspec.yaml → Flutter/Dart
package.json → Node.js (JS/TS)
composer.json → PHP

Use the correct test/lint commands for the detected language.

Tiered Workflow — Pick the right tier FIRST

Tier	Condition	Path
Micro	< 20 lines, ≤2 files, no hub/bridge, complexity <10	`/supergraph:tdd` directly → `/supergraph:verify` (skip analyze/plan)
Standard	≤5 files, clear requirement, no cross-boundary	`/supergraph:analyze` → `/supergraph:plan` (lightweight) → `/supergraph:execute` → `/supergraph:fix` → `/supergraph:verify`
Full	>5 files, ambiguous, hub/bridge, cross-boundary, or blast radius >5	Full pipeline below (`scan → analyze → sdd → plan → ...`)

When in doubt, pick one tier lower — upgrade if complexity reveals itself.

Full Pipeline (Tier 3)

Step 0: Context

Read /supergraph:scan and execute it. NEVER start full-pipeline work without graph context.

Step 1: Analyze

Read /supergraph:analyze and execute it. Frame problem, check graph risk (hub/bridge/cross-boundary), propose approaches, get approval.

Step 2: SDD (Software Design Document)

Read /supergraph:sdd and execute it. Define architecture diagrams, data/interface contracts, platform matrix, failure modes, ADRs. Get approval before planning.

Step 3: Plan

Read /supergraph:plan and execute it. blast_radius → identify affected files. Tasks 2-5 min each. User approval. Save plan to docs/supergraph/plans/ for resume capability.

Step 4: Execute TDD

Read /supergraph:tdd and execute it. Each task: RED → GREEN → REFACTOR. No exceptions.

Step 5: Auto-Fix Loop

After ALL coding, read /supergraph:fix and execute it.

iteration = 0
while iteration < 3:
    run tests → if fail: fix, iteration++, continue
    run lint  → if fail: fix, iteration++, continue
    graph review → if critical: fix, iteration++, continue
    break
if iteration >= 3: STOP, ask user

Step 6: Integration (optional)

Read /supergraph:integration and execute it. Run integration/e2e tests if configured.

Step 7: Verify

Read /supergraph:verify and execute it. NO completion claims without fresh verification evidence.

Step 8: Final Review

Read /supergraph:review and execute it. All checks pass before merge.

Hard Rules

NEVER code without a plan
NEVER implement without a failing test
NEVER read entire codebase — use blast_radius
NEVER modify hub nodes without user approval
NEVER skip the auto-fix loop
NEVER commit if tests fail or review has CRITICAL
ALWAYS use graph MCP tools before assuming relationships
ALWAYS detect language and use correct commands
ALWAYS read the relevant skill file before executing each phase
ALWAYS save plan to file for long-running/team work
ALWAYS respond in the user's language — announcements, summaries, and all user-facing text must match the language the user wrote in (e.g. if user writes in Vietnamese, respond and announce in Vietnamese; if English, use English). The hardcoded announce strings in skill files are templates only — translate them before output.
USE Serena MCP tools when available — get_diagnostics_for_file for type errors, find_referencing_symbols/find_implementations for impact analysis, replace_symbol_body/rename_symbol for targeted edits (prefer over raw text edits)

Escalation

Condition	Action
Blast radius > 20 files	STOP — discuss with user
Hub node modification	REQUIRE user approval
Community boundary crossing	REQUIRE justification
Surprise score > 0.7	REQUIRE investigation
New circular dependency	BLOCK
Fix fails 3 times	STOP — ask user

MCP Tools

Tool	Purpose
`get_stats`	Repo overview
`index_directory`	Index codebase
`index_incremental`	Fast reindex
`blast_radius`	Find affected files
`blast_radius_visualize`	Visual impact
`find_dependencies`	What does X depend on?
`find_dependents`	What breaks if X changes?
`find_transitive_deps`	Deep chains
`find_communities`	Module boundaries
`find_hub_nodes`	Central risky files
`find_bridge_nodes`	Cross-module coupling
`find_cycles`	Circular deps
`find_symbol`	Locate symbol
`find_callers`	Who calls X?
`find_callees`	What does X call?
`find_similar`	Pattern match
`surprise_score`	Unexpected deps
`find_tests_for`	Tests for file
`find_untested_files`	Coverage gaps
Serena tools (via `mcp__serena__*`)
`serena.find_referencing_symbols`	Find all callers/usages of a symbol
`serena.find_implementations`	All implementations of interface/abstract
`serena.get_diagnostics_for_file`	IDE-level type errors for a file
`serena.rename_symbol`	Safe codebase-wide symbol rename
`serena.replace_symbol_body`	Targeted function body replacement
`serena.get_symbols_overview`	Project structure map

supergraph

About