diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index bbe54a4a9e..b755bbc3ab 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.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: [""]` - 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) diff --git a/.github/aw/serena-tool.md b/.github/aw/serena-tool.md new file mode 100644 index 0000000000..b95c22085b --- /dev/null +++ b/.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: [""] # 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) diff --git a/.github/aw/update-agentic-workflow.md b/.github/aw/update-agentic-workflow.md index aaa3fc4aec..888fe9d852 100644 --- a/.github/aw/update-agentic-workflow.md +++ b/.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) diff --git a/.github/workflows/functional-programming-enhancer.lock.yml b/.github/workflows/functional-programming-enhancer.lock.yml index e6c27f09b7..d848782398 100644 --- a/.github/workflows/functional-programming-enhancer.lock.yml +++ b/.github/workflows/functional-programming-enhancer.lock.yml @@ -19,13 +19,13 @@ # gh aw compile # For more information: https://github.com/githubnext/gh-aw/blob/main/.github/aw/github-agentic-workflows.md # -# Identifies opportunities to apply moderate functional programming techniques systematically - immutability, functional initialization, and transformative data operations +# Identifies opportunities to apply moderate functional programming techniques systematically - immutability, functional options, pure functions, and reusable logic wrappers # # Resolved workflow manifest: # Imports: # - shared/reporting.md # -# frontmatter-hash: 1c230019fe040d970438c0cfa9637baca027dfce5b1fae8f2ed4076e8d6e2818 +# frontmatter-hash: 878e4f95faf76dcbd2cb9fa47f1628ece34e71e9b605146a6a4c469a927b805d name: "Functional Programming Enhancer" "on": @@ -699,8 +699,11 @@ jobs: # - Bash(git rm:*) # - Bash(git status) # - Bash(git switch:*) + # - Bash(grep -r 'func New' --include='*.go' pkg/) + # - Bash(grep -r 'global\|Global' --include='*.go' pkg/) # - Bash(grep -r 'make(' --include='*.go' pkg/) # - Bash(grep -r 'range' --include='*.go' pkg/) + # - Bash(grep -r 'sync\.' --include='*.go' pkg/) # - Bash(grep -r 'var ' --include='*.go' pkg/) # - Bash(grep) # - Bash(head) @@ -783,7 +786,7 @@ jobs: GH_AW_TOOL_BINS=""; command -v go >/dev/null 2>&1 && GH_AW_TOOL_BINS="$(go env GOROOT)/bin:$GH_AW_TOOL_BINS"; [ -n "$JAVA_HOME" ] && GH_AW_TOOL_BINS="$JAVA_HOME/bin:$GH_AW_TOOL_BINS"; [ -n "$CARGO_HOME" ] && GH_AW_TOOL_BINS="$CARGO_HOME/bin:$GH_AW_TOOL_BINS"; [ -n "$GEM_HOME" ] && GH_AW_TOOL_BINS="$GEM_HOME/bin:$GH_AW_TOOL_BINS"; [ -n "$CONDA" ] && GH_AW_TOOL_BINS="$CONDA/bin:$GH_AW_TOOL_BINS"; [ -n "$PIPX_BIN_DIR" ] && GH_AW_TOOL_BINS="$PIPX_BIN_DIR:$GH_AW_TOOL_BINS"; [ -n "$SWIFT_PATH" ] && GH_AW_TOOL_BINS="$SWIFT_PATH:$GH_AW_TOOL_BINS"; [ -n "$DOTNET_ROOT" ] && GH_AW_TOOL_BINS="$DOTNET_ROOT:$GH_AW_TOOL_BINS"; export GH_AW_TOOL_BINS mkdir -p "$HOME/.cache" sudo -E awf --env-all --env "ANDROID_HOME=${ANDROID_HOME}" --env "ANDROID_NDK=${ANDROID_NDK}" --env "ANDROID_NDK_HOME=${ANDROID_NDK_HOME}" --env "ANDROID_NDK_LATEST_HOME=${ANDROID_NDK_LATEST_HOME}" --env "ANDROID_NDK_ROOT=${ANDROID_NDK_ROOT}" --env "ANDROID_SDK_ROOT=${ANDROID_SDK_ROOT}" --env "AZURE_EXTENSION_DIR=${AZURE_EXTENSION_DIR}" --env "CARGO_HOME=${CARGO_HOME}" --env "CHROMEWEBDRIVER=${CHROMEWEBDRIVER}" --env "CONDA=${CONDA}" --env "DOTNET_ROOT=${DOTNET_ROOT}" --env "EDGEWEBDRIVER=${EDGEWEBDRIVER}" --env "GECKOWEBDRIVER=${GECKOWEBDRIVER}" --env "GEM_HOME=${GEM_HOME}" --env "GEM_PATH=${GEM_PATH}" --env "GOPATH=${GOPATH}" --env "GOROOT=${GOROOT}" --env "HOMEBREW_CELLAR=${HOMEBREW_CELLAR}" --env "HOMEBREW_PREFIX=${HOMEBREW_PREFIX}" --env "HOMEBREW_REPOSITORY=${HOMEBREW_REPOSITORY}" --env "JAVA_HOME=${JAVA_HOME}" --env "JAVA_HOME_11_X64=${JAVA_HOME_11_X64}" --env "JAVA_HOME_17_X64=${JAVA_HOME_17_X64}" --env "JAVA_HOME_21_X64=${JAVA_HOME_21_X64}" --env "JAVA_HOME_25_X64=${JAVA_HOME_25_X64}" --env "JAVA_HOME_8_X64=${JAVA_HOME_8_X64}" --env "NVM_DIR=${NVM_DIR}" --env "PIPX_BIN_DIR=${PIPX_BIN_DIR}" --env "PIPX_HOME=${PIPX_HOME}" --env "RUSTUP_HOME=${RUSTUP_HOME}" --env "SELENIUM_JAR_PATH=${SELENIUM_JAR_PATH}" --env "SWIFT_PATH=${SWIFT_PATH}" --env "VCPKG_INSTALLATION_ROOT=${VCPKG_INSTALLATION_ROOT}" --env "GH_AW_TOOL_BINS=$GH_AW_TOOL_BINS" --tty --container-workdir "${GITHUB_WORKSPACE}" --mount /tmp:/tmp:rw --mount "${HOME}/.cache:${HOME}/.cache:rw" --mount "${GITHUB_WORKSPACE}:${GITHUB_WORKSPACE}:rw" --mount /opt/hostedtoolcache:/opt/hostedtoolcache:ro --mount /opt/gh-aw:/opt/gh-aw:ro --allow-domains '*.githubusercontent.com,anthropic.com,api.anthropic.com,api.github.com,api.snapcraft.io,archive.ubuntu.com,azure.archive.ubuntu.com,cdn.playwright.dev,codeload.github.com,crl.geotrust.com,crl.globalsign.com,crl.identrust.com,crl.sectigo.com,crl.thawte.com,crl.usertrust.com,crl.verisign.com,crl3.digicert.com,crl4.digicert.com,crls.ssl.com,files.pythonhosted.org,ghcr.io,github-cloud.githubusercontent.com,github-cloud.s3.amazonaws.com,github.com,github.githubassets.com,go.dev,golang.org,goproxy.io,host.docker.internal,json-schema.org,json.schemastore.org,keyserver.ubuntu.com,lfs.github.com,objects.githubusercontent.com,ocsp.digicert.com,ocsp.geotrust.com,ocsp.globalsign.com,ocsp.identrust.com,ocsp.sectigo.com,ocsp.ssl.com,ocsp.thawte.com,ocsp.usertrust.com,ocsp.verisign.com,packagecloud.io,packages.cloud.google.com,packages.microsoft.com,pkg.go.dev,playwright.download.prss.microsoft.com,ppa.launchpad.net,proxy.golang.org,pypi.org,raw.githubusercontent.com,registry.npmjs.org,s.symcb.com,s.symcd.com,security.ubuntu.com,sentry.io,statsig.anthropic.com,sum.golang.org,ts-crl.ws.symantec.com,ts-ocsp.ws.symantec.com' --log-level info --proxy-logs-dir /tmp/gh-aw/sandbox/firewall/logs --enable-host-access --image-tag 0.11.2 --agent-image act \ - -- /bin/bash -c 'source /opt/gh-aw/actions/sanitize_path.sh "$GH_AW_TOOL_BINS$(find /opt/hostedtoolcache -maxdepth 4 -type d -name bin 2>/dev/null | tr '\''\n'\'' '\'':'\'')$PATH" && claude --print --disable-slash-commands --no-chrome --mcp-config /tmp/gh-aw/mcp-config/mcp-servers.json --allowed-tools '\''Bash(cat),Bash(date),Bash(echo),Bash(find pkg -name '\''\'\'''\''*.go'\''\'\'''\'' -type f),Bash(git add:*),Bash(git branch:*),Bash(git checkout:*),Bash(git commit:*),Bash(git merge:*),Bash(git rm:*),Bash(git status),Bash(git switch:*),Bash(grep -r '\''\'\'''\''make('\''\'\'''\'' --include='\''\'\'''\''*.go'\''\'\'''\'' pkg/),Bash(grep -r '\''\'\'''\''range'\''\'\'''\'' --include='\''\'\'''\''*.go'\''\'\'''\'' pkg/),Bash(grep -r '\''\'\'''\''var '\''\'\'''\'' --include='\''\'\'''\''*.go'\''\'\'''\'' pkg/),Bash(grep),Bash(head),Bash(ls),Bash(pwd),Bash(sort),Bash(tail),Bash(uniq),Bash(wc),Bash(yq),BashOutput,Edit,ExitPlanMode,Glob,Grep,KillBash,LS,MultiEdit,NotebookEdit,NotebookRead,Read,Task,TodoWrite,Write,mcp__github__download_workflow_run_artifact,mcp__github__get_code_scanning_alert,mcp__github__get_commit,mcp__github__get_dependabot_alert,mcp__github__get_discussion,mcp__github__get_discussion_comments,mcp__github__get_file_contents,mcp__github__get_job_logs,mcp__github__get_label,mcp__github__get_latest_release,mcp__github__get_me,mcp__github__get_notification_details,mcp__github__get_pull_request,mcp__github__get_pull_request_comments,mcp__github__get_pull_request_diff,mcp__github__get_pull_request_files,mcp__github__get_pull_request_review_comments,mcp__github__get_pull_request_reviews,mcp__github__get_pull_request_status,mcp__github__get_release_by_tag,mcp__github__get_secret_scanning_alert,mcp__github__get_tag,mcp__github__get_workflow_run,mcp__github__get_workflow_run_logs,mcp__github__get_workflow_run_usage,mcp__github__issue_read,mcp__github__list_branches,mcp__github__list_code_scanning_alerts,mcp__github__list_commits,mcp__github__list_dependabot_alerts,mcp__github__list_discussion_categories,mcp__github__list_discussions,mcp__github__list_issue_types,mcp__github__list_issues,mcp__github__list_label,mcp__github__list_notifications,mcp__github__list_pull_requests,mcp__github__list_releases,mcp__github__list_secret_scanning_alerts,mcp__github__list_starred_repositories,mcp__github__list_tags,mcp__github__list_workflow_jobs,mcp__github__list_workflow_run_artifacts,mcp__github__list_workflow_runs,mcp__github__list_workflows,mcp__github__pull_request_read,mcp__github__search_code,mcp__github__search_issues,mcp__github__search_orgs,mcp__github__search_pull_requests,mcp__github__search_repositories,mcp__github__search_users'\'' --debug-file /tmp/gh-aw/agent-stdio.log --verbose --permission-mode bypassPermissions --output-format json "$(cat /tmp/gh-aw/aw-prompts/prompt.txt)"${GH_AW_MODEL_AGENT_CLAUDE:+ --model "$GH_AW_MODEL_AGENT_CLAUDE"}' + -- /bin/bash -c 'source /opt/gh-aw/actions/sanitize_path.sh "$GH_AW_TOOL_BINS$(find /opt/hostedtoolcache -maxdepth 4 -type d -name bin 2>/dev/null | tr '\''\n'\'' '\'':'\'')$PATH" && claude --print --disable-slash-commands --no-chrome --mcp-config /tmp/gh-aw/mcp-config/mcp-servers.json --allowed-tools '\''Bash(cat),Bash(date),Bash(echo),Bash(find pkg -name '\''\'\'''\''*.go'\''\'\'''\'' -type f),Bash(git add:*),Bash(git branch:*),Bash(git checkout:*),Bash(git commit:*),Bash(git merge:*),Bash(git rm:*),Bash(git status),Bash(git switch:*),Bash(grep -r '\''\'\'''\''func New'\''\'\'''\'' --include='\''\'\'''\''*.go'\''\'\'''\'' pkg/),Bash(grep -r '\''\'\'''\''global\|Global'\''\'\'''\'' --include='\''\'\'''\''*.go'\''\'\'''\'' pkg/),Bash(grep -r '\''\'\'''\''make('\''\'\'''\'' --include='\''\'\'''\''*.go'\''\'\'''\'' pkg/),Bash(grep -r '\''\'\'''\''range'\''\'\'''\'' --include='\''\'\'''\''*.go'\''\'\'''\'' pkg/),Bash(grep -r '\''\'\'''\''sync\.'\''\'\'''\'' --include='\''\'\'''\''*.go'\''\'\'''\'' pkg/),Bash(grep -r '\''\'\'''\''var '\''\'\'''\'' --include='\''\'\'''\''*.go'\''\'\'''\'' pkg/),Bash(grep),Bash(head),Bash(ls),Bash(pwd),Bash(sort),Bash(tail),Bash(uniq),Bash(wc),Bash(yq),BashOutput,Edit,ExitPlanMode,Glob,Grep,KillBash,LS,MultiEdit,NotebookEdit,NotebookRead,Read,Task,TodoWrite,Write,mcp__github__download_workflow_run_artifact,mcp__github__get_code_scanning_alert,mcp__github__get_commit,mcp__github__get_dependabot_alert,mcp__github__get_discussion,mcp__github__get_discussion_comments,mcp__github__get_file_contents,mcp__github__get_job_logs,mcp__github__get_label,mcp__github__get_latest_release,mcp__github__get_me,mcp__github__get_notification_details,mcp__github__get_pull_request,mcp__github__get_pull_request_comments,mcp__github__get_pull_request_diff,mcp__github__get_pull_request_files,mcp__github__get_pull_request_review_comments,mcp__github__get_pull_request_reviews,mcp__github__get_pull_request_status,mcp__github__get_release_by_tag,mcp__github__get_secret_scanning_alert,mcp__github__get_tag,mcp__github__get_workflow_run,mcp__github__get_workflow_run_logs,mcp__github__get_workflow_run_usage,mcp__github__issue_read,mcp__github__list_branches,mcp__github__list_code_scanning_alerts,mcp__github__list_commits,mcp__github__list_dependabot_alerts,mcp__github__list_discussion_categories,mcp__github__list_discussions,mcp__github__list_issue_types,mcp__github__list_issues,mcp__github__list_label,mcp__github__list_notifications,mcp__github__list_pull_requests,mcp__github__list_releases,mcp__github__list_secret_scanning_alerts,mcp__github__list_starred_repositories,mcp__github__list_tags,mcp__github__list_workflow_jobs,mcp__github__list_workflow_run_artifacts,mcp__github__list_workflow_runs,mcp__github__list_workflows,mcp__github__pull_request_read,mcp__github__search_code,mcp__github__search_issues,mcp__github__search_orgs,mcp__github__search_pull_requests,mcp__github__search_repositories,mcp__github__search_users'\'' --debug-file /tmp/gh-aw/agent-stdio.log --verbose --permission-mode bypassPermissions --output-format json "$(cat /tmp/gh-aw/aw-prompts/prompt.txt)"${GH_AW_MODEL_AGENT_CLAUDE:+ --model "$GH_AW_MODEL_AGENT_CLAUDE"}' env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} BASH_DEFAULT_TIMEOUT_MS: 60000 @@ -1070,7 +1073,7 @@ jobs: uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 env: WORKFLOW_NAME: "Functional Programming Enhancer" - WORKFLOW_DESCRIPTION: "Identifies opportunities to apply moderate functional programming techniques systematically - immutability, functional initialization, and transformative data operations" + WORKFLOW_DESCRIPTION: "Identifies opportunities to apply moderate functional programming techniques systematically - immutability, functional options, pure functions, and reusable logic wrappers" HAS_PATCH: ${{ needs.agent.outputs.has_patch }} with: script: | diff --git a/pkg/cli/commands.go b/pkg/cli/commands.go index ed766b846a..b9380e080d 100644 --- a/pkg/cli/commands.go +++ b/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 diff --git a/pkg/cli/copilot-agents.go b/pkg/cli/copilot-agents.go index c8d4bf4e10..3e5c43c4a4 100644 --- a/pkg/cli/copilot-agents.go +++ b/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() diff --git a/pkg/cli/fix_command.go b/pkg/cli/fix_command.go index 14ad4b7b56..52dca680e9 100644 --- a/pkg/cli/fix_command.go +++ b/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") diff --git a/pkg/cli/init.go b/pkg/cli/init.go index eb459c077e..68ab56c033 100644 --- a/pkg/cli/init.go +++ b/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") diff --git a/pkg/cli/templates/create-agentic-workflow.md b/pkg/cli/templates/create-agentic-workflow.md index bbe54a4a9e..b755bbc3ab 100644 --- a/pkg/cli/templates/create-agentic-workflow.md +++ b/pkg/cli/templates/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: [""]` - 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) diff --git a/pkg/cli/templates/serena-tool.md b/pkg/cli/templates/serena-tool.md new file mode 100644 index 0000000000..b95c22085b --- /dev/null +++ b/pkg/cli/templates/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: [""] # 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) diff --git a/pkg/cli/templates/update-agentic-workflow.md b/pkg/cli/templates/update-agentic-workflow.md index aaa3fc4aec..888fe9d852 100644 --- a/pkg/cli/templates/update-agentic-workflow.md +++ b/pkg/cli/templates/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) diff --git a/pkg/cli/upgrade_command.go b/pkg/cli/upgrade_command.go index a69e1d1786..457933821e 100644 --- a/pkg/cli/upgrade_command.go +++ b/pkg/cli/upgrade_command.go @@ -300,6 +300,12 @@ func updateAgentFiles(verbose bool) error { return fmt.Errorf("failed to update upgrade workflows prompt: %w", err) } + // Update Serena tool documentation + if err := ensureSerenaTool(verbose, false); err != nil { + upgradeLog.Printf("Failed to update Serena tool documentation: %v", err) + return fmt.Errorf("failed to update Serena tool documentation: %w", err) + } + // Upgrade copilot-setup-steps.yml version actionMode := workflow.DetectActionMode(GetVersion()) if err := upgradeCopilotSetupSteps(verbose, actionMode, GetVersion()); err != nil {