Skip to content

datit309/supergraph / plugins/supergraph/skills/serena

Serena code intelligence — LSP-powered symbol navigation, diagnostics, and targeted code surgery. Activate before complex refactors, cross-file analysis, or when graph tools need symbol-level depth.

/supergraph:serena

Activate Serena MCP for LSP-powered code intelligence: symbol navigation, type diagnostics, and safe code surgery.

CRITICAL: Call initial_instructions first when starting any Serena work — it loads the Serena Instructions Manual with project-specific context.

When to Use

  • Before complex refactors: rename across codebase, API signature changes
  • When blast radius is unclear and graph tools lack symbol-level depth
  • Before review: verify all call sites of changed symbols are updated
  • During fix: triage type errors before running test suite
  • After architectural changes: verify no orphaned references remain
  • Large-scale refactors: safe_delete_symbol, rename_symbol across entire project

Setup

1. Load instructions (MANDATORY first step)

mcp__plugin_serena_serena__initial_instructions()
# or
mcp__serena__initial_instructions()

2. Activate project

mcp__plugin_serena_serena__activate_project()

3. Get project overview

mcp__plugin_serena_serena__get_symbols_overview()

Returns top-level symbols, classes, functions — fast structural map of the codebase.

Tool Reference

Navigation

ToolUse case
find_symbolLocate a symbol by name across codebase
find_declarationJump to where a symbol is declared
find_implementationsFind all implementations of an interface / abstract class
find_referencing_symbolsFind all callers and usages of a symbol

Setup / Lifecycle

ToolUse case
activate_projectRegister project with Serena — requires mcp__plugin_serena_serena__ namespace
get_current_configRead Serena's current project configuration
open_dashboardOpen the Serena dashboard UI
execute_shell_commandRun shell commands (use with caution — confirm before destructive ops)

Diagnostics

ToolUse case
get_diagnostics_for_fileIDE-level type errors, lint warnings for a specific file
get_symbols_overviewProject structure overview — top-level symbols map

Code Surgery (prefer over raw text edits)

ToolUse case
replace_symbol_bodyReplace function/method body — exact, no regex risk
insert_after_symbolInsert code after a symbol definition
insert_before_symbolInsert code before a symbol definition
rename_symbolSafe rename across entire codebase
safe_delete_symbolDelete symbol, verify no remaining references

File Operations

ToolUse case
find_fileFind files by name pattern
list_dirList directory contents
read_fileRead file content
search_for_patternRegex search across files
replace_contentReplace text content in file
create_text_fileCreate a new text file

Memory (cross-session context)

ToolUse case
write_memorySave analysis findings for future sessions
read_memoryRecall prior analysis
list_memoriesList all saved memories
edit_memoryUpdate an existing memory
rename_memoryRename an existing memory entry
delete_memoryRemove stale memory

Memory Workflow

Use Serena memory to persist analysis state across sessions — avoids re-deriving complex blast radius mappings:

# Save findings after analysis:
mcp__serena__write_memory(title="auth-refactor-callers", content="find_referencing_symbols(login) = [A, B, C]")

# Recall in next session:
mcp__serena__read_memory(title="auth-refactor-callers")

Integration Points in Other Skills

Serena is invoked as optional hooks inside other supergraph skills:

SkillHookTools used
scanStep 2b/3bactivate_project, get_symbols_overview
planStep 3bfind_referencing_symbols, find_implementations, write_memory
analyzeStep 2bfind_referencing_symbols, find_implementations
tddAfter RED, after GREEN, refactorget_diagnostics_for_file, replace_symbol_body, rename_symbol
executeCode surgery, post-executionreplace_symbol_body, rename_symbol, insert_after_symbol, find_referencing_symbols
fixPre-loop + each iterationget_diagnostics_for_file, replace_symbol_body, rename_symbol
verifyStep 3bget_diagnostics_for_file
reviewStep 3bfind_referencing_symbols, find_implementations, get_diagnostics_for_file, write_memory
integrationPost-testfind_referencing_symbols, get_diagnostics_for_file
architectureStep 2get_symbols_overview
database-migrationsImpact checkfind_referencing_symbols
browser-agentComponent impactfind_referencing_symbols
flutter-dart-code-reviewMCP-Integrated Reviewget_diagnostics_for_file, find_referencing_symbols, find_implementations

MCP Tool Name Variants

Two variants may be present depending on project setup:

# Plugin variant (full feature set — file ops + symbol nav):
mcp__plugin_serena_serena__<tool>

# Direct variant (symbol navigation focus):
mcp__serena__<tool>

Use whichever responds. If both are available: prefer mcp__plugin_serena_serena__ for file operations, mcp__serena__ for symbol navigation.

Fallback

If Serena MCP is not available:

  • Log: "Serena unavailable, skipping symbol intelligence step"
  • Do NOT block workflow — all Serena steps are optional enhancements
  • Fall back to graph MCP tools + Read/Bash/grep for the same purpose

Rules

  • Always call initial_instructions before any other Serena tool
  • Prefer replace_symbol_body and rename_symbol over raw text edits for code changes
  • Use safe_delete_symbol instead of manual deletion — it verifies no remaining references
  • Save complex analysis to Serena memory when it may be needed across sessions
  • Never use execute_shell_command for destructive operations without user confirmation
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall