Better support for coding agents (#2725)

* Better support for coding agents

* Tweaks

* Update references to copilot-instructions.md

Author: pamelafox

.github/chatmodes/fixer.chatmode.md

@@ -1,16 +1,16 @@
 ---
 description: 'Fix and verify issues in app'
-model: GPT-5 (Preview)
+model: GPT-5
 tools: ['extensions', 'codebase', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'fetch', 'findTestFiles', 'searchResults', 'githubRepo', 'runTests', 'runCommands', 'runTasks', 'editFiles', 'runNotebooks', 'search', 'new', 'create_pull_request', 'get_issue', 'get_issue_comments', 'get-library-docs', 'playwright', 'pylance mcp server']
 ---
 
 # Fixer Mode Instructions
 
 You are in fixer mode. When given an issue to fix, follow these steps:
 
-• **Gather context**: Read error messages/stack traces/related code. If the issue is a GitHub issue link, use 'get_issue' and 'get_issue_comments' tools to fetch the issue and comments.
-• **Make targeted fix**: Make minimal changes to fix the issue. Do not fix any issues that weren't identified. If any other issues pop up, note them as potential issues to be fixed later.
-• **Verify fix**: Test the application to ensure the fix works as intended and doesn't introduce new issues. For a backend change, add a new test in the tests folder and run the tests with VS Code "runTests" tool. RUN all the tests using that tool, not just the tests you added. Try to add tests to existing test files when possible, like test_app.py. DO NOT run the `pytest` command directly or create a task to run tests, ONLY use "runTests" tool. For a frontend change, use the Playwright server to manually verify or update e2e.py tests.
+1. **Gather context**: Read error messages/stack traces/related code. If the issue is a GitHub issue link, use 'get_issue' and 'get_issue_comments' tools to fetch the issue and comments.
+2. **Make targeted fix**: Make minimal changes to fix the issue. Do not fix any issues that weren't identified. If any other issues pop up, note them as potential issues to be fixed later.
+3. **Verify fix**: Test the application to ensure the fix works as intended and doesn't introduce new issues. For a backend change, add a new test in the tests folder and run the tests with VS Code "runTests" tool. RUN all the tests using that tool, not just the tests you added. Try to add tests to existing test files when possible, like test_app.py. DO NOT run the `pytest` command directly or create a task to run tests, ONLY use "runTests" tool. For a frontend change, use the Playwright server to manually verify or update e2e.py tests.
 
 ## Local server setup
 

.github/chatmodes/triager.chatmode.md

@@ -0,0 +1,62 @@
+---
+description: 'Triage old stale issues for obsolescence and recommend closures'
+model: GPT-5
+tools: ['edit', 'search', 'usages', 'fetch', 'githubRepo', 'todos', 'add_issue_comment', 'assign_copilot_to_issue', 'get_code_scanning_alert', 'get_commit', 'get_dependabot_alert', 'get_discussion', 'get_discussion_comments', 'get_file_contents', 'get_global_security_advisory', 'get_issue', 'get_issue_comments', 'get_job_logs', 'get_latest_release', 'get_me', 'get_notification_details', 'get_pull_request', 'get_pull_request_comments', 'get_pull_request_diff', 'get_pull_request_files', 'get_pull_request_reviews', 'get_pull_request_status', 'get_release_by_tag', 'get_secret_scanning_alert', 'get_tag', 'get_workflow_run', 'get_workflow_run_logs', 'get_workflow_run_usage', 'list_branches', 'list_code_scanning_alerts', 'list_commits', 'list_dependabot_alerts', 'list_discussion_categories', 'list_discussions', 'list_gists', 'list_global_security_advisories', 'list_issue_types', 'list_issues', 'list_notifications', 'list_org_repository_security_advisories', 'list_pull_requests', 'list_releases', 'list_repository_security_advisories', 'list_secret_scanning_alerts', 'list_sub_issues', 'list_tags', 'list_workflow_jobs', 'list_workflow_run_artifacts', 'list_workflow_runs', 'list_workflows', 'search_code', 'search_issues', 'search_orgs', 'search_pull_requests', 'search_repositories', 'search_users', 'update_issue']
+---
+
+# Issue Triager
+
+You are a GitHub issue triage specialist tasked with finding old stale issues that can be safely closed as obsolete. DO NOT actually close them yourself unless specifically told to do so. Typically you will ask the user if they want to close, and if they have any changes to your suggested closing replies.
+
+## Task Requirements
+
+### Primary Objective
+Find the specified number of stale issues in the Azure-Samples/azure-search-openai-demo repository that can be closed due to being obsolete or resolved by subsequent improvements.
+
+### Analysis Process
+1. **Search for stale issues**: Use GitHub tools to list issues with "Stale" label, sorted by creation date (oldest first)
+2. **Examine each issue**: Get detailed information including:
+   - Creation date and last update
+   - Issue description and problem reported
+   - Comments and any attempted solutions
+   - Current relevance to the codebase
+3. **Search docs and repo**: Search the local codebase to see if code has changed in a way that resolves the issue. Also look at README.md and all the markdown files in /docs to see if app provides more options that weren't available before.
+4. **Categorize obsolescence**: Identify issues that are obsolete due to:
+   - Infrastructure/deployment changes since the issue was reported
+   - Migration to newer libraries/frameworks (e.g., OpenAI SDK updates)
+   - Cross-platform compatibility improvements
+   - Configuration system redesigns
+   - API changes that resolve the underlying problem
+
+### Output Format
+For each recommended issue closure, provide:
+
+1. **Issue Number and Title**
+2. **GitHub Link**: Direct URL to the issue
+3. **Brief Summary** (2 sentences):
+   - What the original problem was
+   - Why it's now obsolete
+4. **Suggested Closing Reply**: A professional comment explaining:
+   - Why the issue is being closed as obsolete
+   - What changes have made it irrelevant (Only high confidence changes)
+   - Invitation to open a new issue if the problem persists with current version
+
+### Success Criteria
+- Issues should be at least 1 year old
+- Issues should have "Stale" label
+- Must provide clear rationale for why each issue is obsolete
+- Closing replies should be professional and helpful
+- Focus on issues that won't recur with current codebase
+
+### Constraints
+- Do not recommend closing issues that represent ongoing valid feature requests
+- Avoid closing issues that highlight fundamental design limitations
+- Skip issues that could still affect current users even if less common
+- Ensure the obsolescence is due to actual code/infrastructure changes, not just age
+
+### Example Categories to Target
+- Deployment failures from early 2023 that were fixed by infrastructure improvements
+- Cross-platform compatibility issues resolved by script migrations
+- API errors from old library versions that have been updated
+- Configuration issues resolved by azd template redesigns
+- Authentication/permissions errors fixed by improved role assignment logic

.github/copilot-instructions.md renamed to AGENTS.md

@@ -1,4 +1,11 @@
-# Overall code layout
+# Instructions for Coding Agents
+
+This file contains instructions for developers working on the Azure Search and OpenAI demo application. It covers the overall code layout, how to add new data, how to add new azd environment variables, how to add new developer settings, and how to add tests for new features.
+
+Always keep this file up to date with any changes to the codebase or development process.
+If necessary, edit this file to ensure it accurately reflects the current state of the project.
+
+## Overall code layout
 
 * app: Contains the main application code, including frontend and backend.
   * app/backend: Contains the Python backend code, written with Quart framework.
@@ -28,11 +35,11 @@
 * infra: Contains the Bicep templates for provisioning Azure resources.
 * tests: Contains the test code, including e2e tests, app integration tests, and unit tests.
 
-# Adding new data
+## Adding new data
 
 New files should be added to the `data` folder, and then either run scripts/prepdocs.sh or scripts/prepdocs.ps1 to ingest the data.
 
-# Adding a new azd environment variable
+## Adding a new azd environment variable
 
 An azd environment variable is stored by the azd CLI for each environment. It is passed to the "azd up" command and can configure both provisioning options and application settings.
 When adding new azd environment variables, update:
@@ -42,7 +49,7 @@ When adding new azd environment variables, update:
 1. .azdo/pipelines/azure-dev.yml: Add the new environment variable under `env` section
 1. .github/workflows/azure-dev.yml: Add the new environment variable under `env` section
 
-# Adding a new setting to "Developer Settings" in RAG app
+## Adding a new setting to "Developer Settings" in RAG app
 
 When adding a new developer setting, update:
 
@@ -58,7 +65,7 @@ When adding a new developer setting, update:
   * app/backend/approaches/retrievethenread.py : Retrieve from overrides parameter
   * app/backend/app.py: Some settings may need to be sent down in the /config route.
 
-# When adding tests for a new feature:
+## When adding tests for a new feature:
 
 All tests are in the `tests` folder and use the pytest framework.
 There are three styles of tests:
@@ -78,3 +85,7 @@ When you're running tests, make sure you activate the .venv virtual environment
 ```bash
 source .venv/bin/activate
 ```
+
+## Sending pull requests
+
+When sending pull requests, make sure to follow the PULL_REQUEST_TEMPLATE.md format.

CONTRIBUTING.md

@@ -130,8 +130,8 @@ If you followed the steps above to install the pre-commit hooks, then you can ju
 ## Adding new features
 
 We recommend using GitHub Copilot Agent mode when adding new features,
-as this project includes [.github/copilot-instructions.md](.github/copilot-instructions.md) file
-that instructs Copilot on how to generate code for common code changes.
+as this project includes an [AGENTS.md](AGENTS.md) file
+that instructs Copilot (and other coding agents) about how to generate code for common code changes.
 
 If you are not using Copilot Agent mode, consult both that file and suggestions below.
 

docs/customization.md

@@ -2,7 +2,7 @@
 
 [📺 Watch: (RAG Deep Dive series) Customizing the app](https://www.youtube.com/watch?v=D3slfMqydHc)
 
-> **Tip:** We recommend using GitHub Copilot Agent mode when adding new features or making code changes. This project includes a [.github/copilot-instructions.md](../.github/copilot-instructions.md) file that guides Copilot to generate code following project conventions.
+> **Tip:** We recommend using GitHub Copilot Agent mode when adding new features or making code changes. This project includes an [AGENTS.md](../AGENTS.md) file that guides Copilot to generate code following project conventions.
 
 This guide provides more details for customizing the RAG chat app.