Extract Serena language server documentation to separate reference file

.github/aw/create-agentic-workflow.md

@@ -133,7 +133,7 @@ DO NOT ask all these questions at once; instead, engage in a back-and-forth conv
      - Browser automation → `playwright`
      - Media manipulation → `ffmpeg` (installed via `steps:`)
      - Code parsing/analysis → `ast-grep`, `codeql` (installed via `steps:`)
-     - **Language server for code analysis** → `serena: ["<language>"]` - Detect the repository's primary programming language (check file extensions, go.mod, package.json, requirements.txt, etc.) and specify it in the array. Supported languages: `go`, `typescript`, `python`, `ruby`, `rust`, `java`, `cpp`, `csharp`, and many more (see `.serena/project.yml` for full list).
+     - **Advanced static analysis** → See `.github/aw/serena-tool.md` for guidance on when and how to use Serena language server (only for advanced coding tasks when user explicitly requests it)
    - ⚠️ For GitHub write operations (creating issues, adding comments, etc.), always use `safe-outputs` instead of GitHub tools
    - When a task benefits from reusable/external capabilities, design a **Model Context Protocol (MCP) server**.
    - For each tool / MCP server:
@@ -176,11 +176,8 @@ DO NOT ask all these questions at once; instead, engage in a back-and-forth conv
    - **Always use `safe-outputs` instead** for any GitHub write operations (creating issues, adding comments, etc.)
    - **Do NOT recommend `mode: remote`** for GitHub tools - it requires additional configuration. Use `mode: local` (default) instead.
 
-   **General tools (Serena language server)**:
-   ```yaml
-   tools:
-     serena: ["go"]  # Update with your programming language (detect from repo)
-   ```
+   **Advanced static analysis tools**:
+   For advanced code analysis tasks, see `.github/aw/serena-tool.md` for when and how to use Serena language server.
 
    ⚠️ **IMPORTANT - Default Tools**: 
    - **`edit` and `bash` are enabled by default** when sandboxing is active (no need to add explicitly)

.github/aw/serena-tool.md

@@ -0,0 +1,86 @@
+# Serena Language Server Tool
+
+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.
+
+## When to Use Serena
+
+⚠️ **Important**: Serena should only be suggested when the user **explicitly requests advanced static analysis** for specific programming languages.
+
+**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
+
+**NOT recommended for:**
+- Simple file editing or text manipulation
+- Basic code generation
+- General workflow automation
+- Tasks that don't require deep code understanding
+
+## Configuration
+
+When a user explicitly asks for advanced static analysis capabilities:
+
+```yaml
+tools:
+  serena: ["<language>"]  # Specify the programming language(s)
+```
+
+**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"]  # For Go repositories requiring advanced static analysis
+```
+
+## User Interaction Pattern
+
+When a user describes a task:
+
+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
+
+**Example conversation:**
+
+User: "I need to refactor the authentication logic across multiple files with proper type safety"
+
+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."
+
+User: "Yes, use Serena"
+
+Agent: *Adds `serena: ["go"]` to the workflow configuration*
+
+## Best Practices
+
+- **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)

.github/aw/update-agentic-workflow.md

@@ -162,11 +162,8 @@ tools:
 - **Always use `safe-outputs` instead** for any GitHub write operations
 - **Do NOT recommend `mode: remote`** for GitHub tools - it requires additional configuration
 
-**General tools (Serena language server)**:
-```yaml
-tools:
-  serena: ["go"]  # Update with the repository's programming language
-```
+**Advanced static analysis tools**:
+For advanced code analysis tasks, see `.github/aw/serena-tool.md` for when and how to use Serena language server.
 
 ⚠️ **IMPORTANT - Default Tools**: 
 - **`edit` and `bash` are enabled by default** when sandboxing is active (no need to add explicitly)

pkg/cli/commands.go

@@ -49,6 +49,9 @@ var debugWorkflowPromptTemplate string
 //go:embed templates/upgrade-agentic-workflows.md
 var upgradeAgenticWorkflowsPromptTemplate string
 
+//go:embed templates/serena-tool.md
+var serenaToolTemplate string
+
 // SetVersionInfo sets the version information for the CLI and workflow package
 func SetVersionInfo(v string) {
 	version = v

pkg/cli/copilot-agents.go

@@ -212,6 +212,18 @@ func ensureUpgradeAgenticWorkflowsPrompt(verbose bool, skipInstructions bool) er
 	)
 }
 
+// ensureSerenaTool ensures that .github/aw/serena-tool.md contains the Serena language server tool documentation
+func ensureSerenaTool(verbose bool, skipInstructions bool) error {
+	return ensureFileMatchesTemplate(
+		filepath.Join(".github", "aw"),
+		"serena-tool.md",
+		serenaToolTemplate,
+		"Serena tool documentation",
+		verbose,
+		skipInstructions,
+	)
+}
+
 // deleteSetupAgenticWorkflowsAgent deletes the setup-agentic-workflows.agent.md file if it exists
 func deleteSetupAgenticWorkflowsAgent(verbose bool) error {
 	gitRoot, err := findGitRoot()

pkg/cli/fix_command.go

@@ -227,6 +227,12 @@ func runFixCommand(workflowIDs []string, write bool, verbose bool, workflowDir s
 		fmt.Fprintf(os.Stderr, "%s\n", console.FormatWarningMessage(fmt.Sprintf("Warning: Failed to update upgrade workflow prompt: %v", err)))
 	}
 
+	// Update Serena tool documentation
+	if err := ensureSerenaTool(verbose, false); err != nil {
+		fixLog.Printf("Failed to update Serena tool documentation: %v", err)
+		fmt.Fprintf(os.Stderr, "%s\n", console.FormatWarningMessage(fmt.Sprintf("Warning: Failed to update Serena tool documentation: %v", err)))
+	}
+
 	// Delete old agent files if write flag is set
 	if write {
 		fixLog.Print("Deleting old agent files")

pkg/cli/init.go

@@ -246,6 +246,16 @@ func initializeBasicRepository(verbose bool) error {
 		fmt.Fprintln(os.Stderr, console.FormatSuccessMessage("Created upgrade workflows prompt"))
 	}
 
+	// Write Serena tool documentation
+	initLog.Print("Writing Serena tool documentation")
+	if err := ensureSerenaTool(verbose, false); err != nil {
+		initLog.Printf("Failed to write Serena tool documentation: %v", err)
+		return fmt.Errorf("failed to write Serena tool documentation: %w", err)
+	}
+	if verbose {
+		fmt.Fprintln(os.Stderr, console.FormatSuccessMessage("Created Serena tool documentation"))
+	}
+
 	return nil
 }
 
@@ -564,6 +574,16 @@ func InitRepository(verbose bool, mcp bool, campaign bool, tokens bool, engine s
 		fmt.Fprintln(os.Stderr, console.FormatSuccessMessage("Created upgrade workflows prompt"))
 	}
 
+	// Write Serena tool documentation
+	initLog.Print("Writing Serena tool documentation")
+	if err := ensureSerenaTool(verbose, false); err != nil {
+		initLog.Printf("Failed to write Serena tool documentation: %v", err)
+		return fmt.Errorf("failed to write Serena tool documentation: %w", err)
+	}
+	if verbose {
+		fmt.Fprintln(os.Stderr, console.FormatSuccessMessage("Created Serena tool documentation"))
+	}
+
 	// Configure MCP if requested
 	if mcp {
 		initLog.Print("Configuring GitHub Copilot Agent MCP integration")