diff --git a/.github/aw/serena-tool.md b/.github/aw/serena-tool.md index 706ebface3..b95c22085b 100644 --- a/.github/aw/serena-tool.md +++ b/.github/aw/serena-tool.md @@ -1,173 +1,86 @@ # Serena Language Server Tool -Serena is a **language service protocol (LSP) MCP server** for semantic code analysis. Use it ONLY when you need deep code understanding beyond text manipulation. +Serena is an **advanced static analysis tool** that provides deep code understanding through language server capabilities. It is designed for **advanced coding tasks** that require sophisticated code analysis. -## Quick Decision: Should I Use Serena? +## When to Use Serena -**✅ YES - Use Serena when you need:** -- Symbol navigation (find all usages of a function/type) -- Call graph analysis across files -- Semantic duplicate detection (not just text matching) -- Refactoring analysis (functions in wrong files, extraction opportunities) -- Type relationships and interface implementations +⚠️ **Important**: Serena should only be suggested when the user **explicitly requests advanced static analysis** for specific programming languages. -**❌ NO - Use simpler tools when:** -- Searching text patterns → Use `grep` -- Editing files → Use `edit` tool -- Running commands → Use `bash` -- Working with YAML/JSON/Markdown → Use `edit` tool -- Simple file operations → Use `bash` or `create` +**Appropriate use cases:** +- Deep code refactoring requiring semantic understanding +- Complex code transformations across multiple files +- Advanced type checking and inference +- Cross-file dependency analysis +- Language-specific semantic analysis -**Rule of thumb**: If `grep` or `bash` can solve it in 1-2 commands, don't use Serena. +**NOT recommended for:** +- Simple file editing or text manipulation +- Basic code generation +- General workflow automation +- Tasks that don't require deep code understanding ## Configuration -Add to workflow frontmatter: +When a user explicitly asks for advanced static analysis capabilities: ```yaml tools: - serena: ["go"] # Specify language(s): go, typescript, python, ruby, rust, java, cpp, csharp + serena: [""] # Specify the programming language(s) ``` -Multi-language repositories: -```yaml -tools: - serena: ["go", "typescript"] # First language is default fallback -``` - -## Available Serena Tools - -### Navigation & Analysis -- `find_symbol` - Search for symbols by name -- `get_symbols_overview` - List all symbols in a file -- `find_referencing_symbols` - Find where a symbol is used -- `find_referencing_code_snippets` - Find code snippets using a symbol -- `search_for_pattern` - Search for code patterns (regex) - -### Code Editing -- `read_file` - Read file with semantic context -- `create_text_file` - Create/overwrite files -- `insert_at_line` - Insert content at line number -- `insert_before_symbol` / `insert_after_symbol` - Insert near symbols -- `replace_lines` - Replace line range -- `replace_symbol_body` - Replace symbol definition -- `delete_lines` - Delete line range - -### Project Management -- `activate_project` - **REQUIRED** - Activate Serena for workspace -- `onboarding` - Analyze project structure -- `restart_language_server` - Restart LSP if needed -- `get_current_config` - View Serena configuration -- `list_dir` - List directory contents - -## Usage Workflow - -### 1. Activate Serena First - -**Always call activate_project before other Serena tools:** - -```javascript -// activate_project tool -{ - "path": "/home/runner/work/gh-aw/gh-aw" -} -``` - -### 2. Combine with Other Tools - -**Best practice**: Use bash for discovery, Serena for analysis +**Supported languages:** +- `go` +- `typescript` +- `python` +- `ruby` +- `rust` +- `java` +- `cpp` +- `csharp` +- And many more (see `.serena/project.yml` for full list) + +## Detection and Usage + +**To detect the repository's primary language:** +1. Check file extensions in the repository +2. Look for language-specific files: + - `go.mod` → Go + - `package.json` → TypeScript/JavaScript + - `requirements.txt` or `pyproject.toml` → Python + - `Cargo.toml` → Rust + - `pom.xml` or `build.gradle` → Java + - etc. + +## Example Configuration ```yaml tools: - serena: ["go"] - bash: - - "find pkg -name '*.go' ! -name '*_test.go'" - - "cat go.mod" - github: - toolsets: [default] -``` - -**Pattern**: -1. Use `bash` to list files -2. Use Serena to analyze semantic structure -3. Use `edit` to make changes - -### 3. Use Cache for Recurring Analysis - -Track analysis state across runs: - -```yaml -tools: - serena: ["go"] - cache-memory: true # Store analysis history -``` - -Load cache → Analyze new/changed files → Save results → Avoid redundant work - -## Common Patterns - -### Pattern 1: Find All Function Usages - -``` -1. Use find_symbol to locate function definition -2. Use find_referencing_code_snippets to find call sites -3. Analyze patterns + serena: ["go"] # For Go repositories requiring advanced static analysis ``` -### Pattern 2: Code Quality Analysis +## User Interaction Pattern -``` -1. Use get_symbols_overview on multiple files -2. Use find_symbol for similar function names -3. Use search_for_pattern for duplicate logic -4. Identify consolidation opportunities -``` +When a user describes a task: -### Pattern 3: Daily Code Analysis +1. **Analyze the request**: Does it require advanced static analysis? +2. **If NO**: Use standard tools (bash, edit, etc.) +3. **If YES**: Ask the user if they want to use Serena for advanced static analysis +4. **Only add Serena** if the user explicitly confirms -``` -1. Load previous state from cache-memory -2. Select files using round-robin or priority -3. Use Serena for semantic analysis -4. Save findings to cache -5. Generate improvement tasks -``` - -## Production Examples - -Workflows successfully using Serena: - -- **go-fan** (97.6% success) - Go module usage analysis with round-robin -- **sergo** (94.4% success) - Daily code quality with 50/50 cached/new strategies -- **semantic-function-refactor** - Function clustering and outlier detection -- **daily-compiler-quality** - Rotating file analysis with cache tracking +**Example conversation:** -## Common Pitfalls +User: "I need to refactor the authentication logic across multiple files with proper type safety" -❌ **Using Serena for non-code files** - Use `edit` for YAML/JSON/Markdown -❌ **Forgetting activate_project** - Always call first -❌ **Not combining with bash** - Use bash for file discovery -❌ **Missing language configuration** - Must specify language(s) +Agent: "This task involves complex cross-file refactoring. Would you like me to use the Serena language server for advanced static analysis? This will provide deeper code understanding but adds complexity to the workflow." -## Supported Languages +User: "Yes, use Serena" -Primary languages with full LSP features: -- `go` (gopls) -- `typescript` (TypeScript/JavaScript) -- `python` (jedi/pyright) -- `ruby` (solargraph) -- `rust` (rust-analyzer) -- `java`, `cpp`, `csharp` +Agent: *Adds `serena: ["go"]` to the workflow configuration* -See `.serena/project.yml` for complete list (25+ languages). +## Best Practices -## Decision Tree - -``` -Task requires code semantics/structure? -├─ NO → Use bash/edit/view -└─ YES - ├─ Simple text search/replace? → Use grep/bash - ├─ Config/data files? → Use edit - └─ Symbol/structure/semantic patterns? → Use Serena ✅ -``` +- **Default to simpler tools** when possible +- **Only suggest Serena** for genuinely complex analysis tasks +- **Ask before adding** Serena to a workflow +- **Explain the benefits** when suggesting Serena +- **Consider the trade-offs** (added complexity vs. better analysis)