datit309/supergraph / plugins/supergraph/skills/serena
serena
UnverifiedSerena 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
| Tool | Use case |
|---|---|
find_symbol | Locate a symbol by name across codebase |
find_declaration | Jump to where a symbol is declared |
find_implementations | Find all implementations of an interface / abstract class |
find_referencing_symbols | Find all callers and usages of a symbol |
Setup / Lifecycle
| Tool | Use case |
|---|---|
activate_project | Register project with Serena — requires mcp__plugin_serena_serena__ namespace |
get_current_config | Read Serena's current project configuration |
open_dashboard | Open the Serena dashboard UI |
execute_shell_command | Run shell commands (use with caution — confirm before destructive ops) |
Diagnostics
| Tool | Use case |
|---|---|
get_diagnostics_for_file | IDE-level type errors, lint warnings for a specific file |
get_symbols_overview | Project structure overview — top-level symbols map |
Code Surgery (prefer over raw text edits)
| Tool | Use case |
|---|---|
replace_symbol_body | Replace function/method body — exact, no regex risk |
insert_after_symbol | Insert code after a symbol definition |
insert_before_symbol | Insert code before a symbol definition |
rename_symbol | Safe rename across entire codebase |
safe_delete_symbol | Delete symbol, verify no remaining references |
File Operations
| Tool | Use case |
|---|---|
find_file | Find files by name pattern |
list_dir | List directory contents |
read_file | Read file content |
search_for_pattern | Regex search across files |
replace_content | Replace text content in file |
create_text_file | Create a new text file |
Memory (cross-session context)
| Tool | Use case |
|---|---|
write_memory | Save analysis findings for future sessions |
read_memory | Recall prior analysis |
list_memories | List all saved memories |
edit_memory | Update an existing memory |
rename_memory | Rename an existing memory entry |
delete_memory | Remove 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:
| Skill | Hook | Tools used |
|---|---|---|
scan | Step 2b/3b | activate_project, get_symbols_overview |
plan | Step 3b | find_referencing_symbols, find_implementations, write_memory |
analyze | Step 2b | find_referencing_symbols, find_implementations |
tdd | After RED, after GREEN, refactor | get_diagnostics_for_file, replace_symbol_body, rename_symbol |
execute | Code surgery, post-execution | replace_symbol_body, rename_symbol, insert_after_symbol, find_referencing_symbols |
fix | Pre-loop + each iteration | get_diagnostics_for_file, replace_symbol_body, rename_symbol |
verify | Step 3b | get_diagnostics_for_file |
review | Step 3b | find_referencing_symbols, find_implementations, get_diagnostics_for_file, write_memory |
integration | Post-test | find_referencing_symbols, get_diagnostics_for_file |
architecture | Step 2 | get_symbols_overview |
database-migrations | Impact check | find_referencing_symbols |
browser-agent | Component impact | find_referencing_symbols |
flutter-dart-code-review | MCP-Integrated Review | get_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_instructionsbefore any other Serena tool - Prefer
replace_symbol_bodyandrename_symbolover raw text edits for code changes - Use
safe_delete_symbolinstead 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_commandfor destructive operations without user confirmation
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| 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 fallback | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| 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 always | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |