From 1eb57d448840beb9694cc48cd98681ac038cf0a4 Mon Sep 17 00:00:00 2001 From: rahuldevikar761 <19936206+rahuldevikar761@users.noreply.github.com> Date: Mon, 10 Nov 2025 21:41:24 -0800 Subject: [PATCH] Add Copilot instructions for code review and validation Added comprehensive instructions for GitHub Copilot to follow during code reviews, including rules for checking keywords, copyright headers, and Agent 365 sample validation. --- .github/copilot-instructions.md | 414 ++++++++++++++++++++++++++++++++ 1 file changed, 414 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..cc0577e0 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,414 @@ +# GitHub Copilot Instructions for Agent365-dotnet + +## Code Review Rules + +### Rule 1: Check for "Kairo" Keyword +- **Description**: Scan code for any occurrence of the keyword "Kairo" +- **Action**: If "Kairo" is found in any code file: + - Flag it for review + - Suggest removal or replacement with appropriate terminology + - Check if it's a legacy reference that needs to be updated +- **Files to check**: All source files (`.cs`, `.csx`, `.py`, `.js`, `.ts`, `.mjs`) in the repository + +### Rule 2: Verify Copyright Headers +- **Description**: Ensure all source code files have proper Microsoft copyright headers +- **Action**: If a source file is missing a copyright header: + - Add the Microsoft copyright header at the top of the file + - The header should be placed before any using/import statements or code + - Maintain proper formatting and spacing + - Use language-appropriate comment syntax + +#### Required Copyright Header Format + +**C# Files (`.cs`, `.csx`):** +```csharp +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. +``` + +**Python Files (`.py`):** +```python +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. +``` + +**JavaScript/TypeScript Files (`.js`, `.ts`, `.mjs`):** +```javascript +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. +``` + +### Implementation Guidelines + +#### When Reviewing Code: +1. **Kairo Check**: + - Search for case-insensitive matches of "Kairo" + - Review context to determine if it's: + - A class name + - A namespace + - A variable name + - A comment reference + - A using statement + - A string literal + - Suggest appropriate alternatives based on the context + +2. **Header Check**: + - Verify the first non-empty lines of source files + - If missing, prepend the copyright header with appropriate comment syntax + - Ensure there's a blank line after the header before other content + - Do not add headers to: + - Auto-generated files: + - C#: Marked with `` or `// `, `.Designer.cs`, `.g.cs` + - Python: Files with auto-generated markers + - JavaScript/TypeScript: `.d.ts` type definitions, files with `@generated` marker + - Files with `#pragma warning disable` at the top for generated code + - Third-party/vendored code + +#### Example of Proper File Structure: + +**C# (`.cs`):** +```csharp +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +using System; +using System.Collections.Generic; +using Microsoft.Extensions.Logging; + +namespace MyNamespace +{ + /// + /// Class documentation + /// + public class MyClass + { + // Rest of the code... + } +} +``` + +**Python (`.py`):** +```python +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. + +import os +import logging +from typing import Optional + +class MyClass: + """Class documentation""" + + def __init__(self): + # Rest of the code... + pass +``` + +**JavaScript/TypeScript (`.js`, `.ts`):** +```javascript +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +import express from 'express'; +import { Logger } from './logger'; + +/** + * Class documentation + */ +class MyClass { + // Rest of the code... +} +``` + +#### Example with File-Scoped Namespace (C# 10+): +```csharp +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +using System; +using System.Threading.Tasks; + +namespace MyNamespace; + +/// +/// Class documentation +/// +public class MyClass +{ + // Rest of the code... +} +``` + +#### Example with Top-Level Statements (C# 9+): +```csharp +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +using System; + +var builder = WebApplication.CreateBuilder(args); + +// Rest of the code... +``` + +### Auto-fix Behavior +When Copilot detects violations: +- **Kairo keyword**: Suggest inline replacement or flag for manual review +- **Missing header**: Automatically suggest adding the copyright header + +### Exclusions +- Test files in `Tests/`, `test/`, `tests/`, or files ending with `.Tests.cs`, `.Test.cs`, `_test.py`, `test_*.py`, `.test.js`, `.spec.js` may have relaxed header requirements (but headers are still recommended) +- Auto-generated files: + - C#: `.g.cs`, `.designer.cs`, files with auto-generated markers + - Python: Files with auto-generated comments + - JavaScript/TypeScript: `.d.ts`, files with `@generated` marker +- Third-party code or vendored dependencies should not be modified +- Configuration files (`.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.md`, `.txt`) do not require copyright headers +- Project metadata files: `.csproj`, `.sln`, `package.json`, `pyproject.toml`, `requirements.txt`, `setup.py` +- Build output directories: + - C#: `bin/`, `obj/` + - Python: `__pycache__/`, `*.pyc`, `dist/`, `build/` + - JavaScript/TypeScript: `node_modules/`, `dist/`, `build/` +- Environment files: `.env`, `.env.example`, `.env.local` +- AssemblyInfo.cs files that are auto-generated + +--- + +## Rule 3: Agent 365 Sample Review and Validation + +### Description +When a developer is adding or updating Agent 365 samples, Copilot must actively validate that the sample follows Agent 365 standards and best practices. This rule applies to any work in sample directories or when README files for samples are being created/modified. + +### When to Apply This Rule +- When user is creating a new sample project +- When user is updating an existing sample +- When user asks for help with sample documentation +- When user requests review of sample code +- When README.md files in sample directories are being edited + +### Validation Actions + +When working with Agent 365 samples, Copilot should **automatically check and report** on the following: + +#### 1. Documentation Validation +**Scan for:** +- [ ] README.md exists in sample directory +- [ ] README has "Demonstrates" section explaining what the sample shows +- [ ] Prerequisites section lists all required tools/services with links: + - Language runtime version (e.g., .NET 8.0+, Python 3.10+, Node.js 18+) + - Package manager (e.g., npm, pip, dotnet) + - Azure OpenAI or OpenAI API key + - Optional: Microsoft 365 Agents Playground + - Optional: dev tunnel +- [ ] Configuration section with example config file snippets: + - C#: `appsettings.json` example + - Python: `.env` or config file example + - JavaScript/TypeScript: `.env` or `config.json` example +- [ ] "How to run this sample" section with step-by-step instructions (language-specific commands) +- [ ] Multiple testing options documented (Playground, WebChat, Teams/M365) +- [ ] Troubleshooting section with common errors and solutions (language-specific) +- [ ] Links to official Agent 365 documentation + +**Action:** If missing, suggest adding the missing sections with appropriate content for the detected language. + +#### 2. Configuration File Validation +**Scan for:** +- [ ] Configuration file exists: + - C#: `appsettings.json` + - Python: `.env`, `config.py`, or `settings.py` + - JavaScript/TypeScript: `.env`, `config.js`, or `config.json` +- [ ] OpenAI/Azure OpenAI configuration section present +- [ ] Token validation settings documented (where applicable) +- [ ] No hardcoded API keys or secrets in committed files +- [ ] Placeholder values use clear naming (e.g., `<>`, `<>`, or empty strings) +- [ ] Example configuration provided in README +- [ ] `.env.example` or equivalent template file provided for environment variables + +**Action:** If secrets detected, **immediately warn** and suggest using user secrets, environment variables, or key vault. + +#### 3. Authentication Configuration Check +**Scan for:** +- [ ] Documentation covers supported authentication types +- [ ] Limitations clearly stated (e.g., "Federated Credentials don't work with dev tunnels") +- [ ] Token validation can be enabled/disabled via configuration +- [ ] Azure Bot setup instructions provided with links +- [ ] Authentication context properly propagated in code + +**Action:** Suggest missing authentication documentation or code patterns. + +#### 4. Code Quality Validation +**Scan for:** +- [ ] All source files have Microsoft copyright headers (`.cs`, `.py`, `.js`, `.ts`, etc.) + - C#: `// Copyright (c) Microsoft Corporation.` (Rule 2) + - Python: `# Copyright (c) Microsoft Corporation.` + - JavaScript/TypeScript: `// Copyright (c) Microsoft Corporation.` +- [ ] No "Kairo" legacy references in any language (Rule 1) +- [ ] Proper error handling with try-catch/try-except where appropriate +- [ ] Logging statements use appropriate framework (ILogger, logging module, console, etc.) +- [ ] No compiler/linter warnings in code +- [ ] Async/await patterns used correctly (for languages that support it) +- [ ] Resource cleanup patterns followed (Dispose, context managers, cleanup functions) + +**Action:** Flag violations and suggest fixes inline. + +#### 5. Project Structure Validation +**Scan for:** +- [ ] Project/dependency file properly configured: + - C#: `.csproj` with required packages + - Python: `requirements.txt` or `pyproject.toml` with dependencies + - JavaScript: `package.json` with dependencies + - TypeScript: `package.json` with dependencies and `tsconfig.json` +- [ ] Launch/debug configuration exists: + - C#: `Properties/launchSettings.json` + - Python: `.vscode/launch.json` (optional but recommended) + - JavaScript/TypeScript: `package.json` scripts or `.vscode/launch.json` +- [ ] `appManifest/` folder exists with: + - `manifest.json` with proper placeholders + - `color.png` icon (192x192) + - `outline.png` icon (32x32) +- [ ] `.gitignore` excludes build artifacts and secrets: + - C#: `bin/`, `obj/`, `*.user` + - Python: `__pycache__/`, `*.pyc`, `.env`, `venv/`, `.venv/` + - JavaScript/TypeScript: `node_modules/`, `dist/`, `.env` + +**Action:** Report missing files and offer to create them. + +#### 6. Observability Implementation Check +**Scan code for:** +- [ ] Activity/tracing framework configured (e.g., `Activity.Current`) +- [ ] Custom spans created for key operations +- [ ] Exception tracking implemented +- [ ] Logging configured at startup +- [ ] Observability appears in configuration + +**Action:** If observability is minimal or missing, suggest patterns to add it. + +#### 7. Server Integration Check +**Scan code for:** +- [ ] Microsoft 365 Agents SDK endpoint configured (typically `/api/messages`) +- [ ] Proper HTTP status codes returned +- [ ] Request/response handling follows SDK patterns +- [ ] Concurrent request handling considered + +**Action:** Validate endpoint configuration and suggest improvements. + +#### 8. Testing Validation +**Check documentation for:** +- [ ] Local testing steps with language-specific commands: + - C#: Visual Studio, VS Code, `dotnet run` + - Python: VS Code, command line with `python main.py` or `uvicorn` + - JavaScript/TypeScript: VS Code, `npm start` or `node index.js` +- [ ] Dev tunnels usage documented (if applicable) +- [ ] Azure deployment steps provided +- [ ] WebChat testing steps included +- [ ] Teams/M365 integration steps with manifest upload instructions +- [ ] Virtual environment setup documented (Python: venv, C#: not needed, JS: not needed) + +**Action:** Flag missing testing scenarios and suggest documentation. + +#### 9. Troubleshooting Documentation +**Scan README for:** +- [ ] Troubleshooting section exists +- [ ] Common configuration errors documented +- [ ] Missing API key errors explained +- [ ] Authentication errors covered +- [ ] Solutions provided (not just error descriptions) + +**Action:** Suggest adding common issues from known sample patterns. + +### Automated Reporting Format + +When reviewing a sample, Copilot should provide a **summary report** like this: + +``` +✅ Agent 365 Sample Validation Report + +Documentation: +✅ README.md exists with all required sections +⚠️ Missing troubleshooting section - suggest adding common errors + +Configuration: +✅ Configuration file present with proper structure (appsettings.json / .env / config.json) +❌ API key placeholder not clear - suggest using "<>" + +Authentication: +✅ Multiple auth types documented +✅ Limitations clearly stated + +Code Quality: +✅ All files have copyright headers +✅ No "Kairo" references found +⚠️ Missing error handling in agent.py line 45 (or MyAgent.cs, index.ts, etc.) + +Project Structure: +✅ All required files present +✅ appManifest folder configured correctly + +Observability: +✅ Logging framework configured +⚠️ Consider adding custom spans for tool execution + +Recommendations: +1. Add troubleshooting section to README with common configuration errors +2. Clarify API key placeholder in configuration file (appsettings.json / .env / config.json) +3. Add error handling around LLM call in agent file (try-catch for C#, try-except for Python, try-catch for JS/TS) +4. Consider adding observability spans for better tracing (Activity for C#, custom spans for Python/JS) +``` + +### Language-Specific Considerations + +**C# Samples:** +- Copyright header: `// Copyright (c) Microsoft Corporation.` +- Config file: `appsettings.json` +- Project file: `*.csproj` +- Run command: `dotnet run` +- Dependencies: NuGet packages + +**Python Samples:** +- Copyright header: `# Copyright (c) Microsoft Corporation.` +- Config file: `.env` or `config.py` +- Dependencies file: `requirements.txt` or `pyproject.toml` +- Run command: `python main.py` or `uvicorn main:app` +- Virtual environment: `venv` or `virtualenv` +- Check for `__pycache__/` in `.gitignore` + +**JavaScript/TypeScript Samples:** +- Copyright header: `// Copyright (c) Microsoft Corporation.` +- Config file: `.env` or `config.json` +- Project file: `package.json` +- TypeScript config: `tsconfig.json` +- Run command: `npm start` or `node index.js` / `ts-node index.ts` +- Dependencies: npm packages +- Check for `node_modules/` in `.gitignore` + +### Proactive Suggestions + +When user says: +- **"Create a sample"** → Ask about which concepts to demonstrate (Notifications, Observability, Tooling) and suggest starting with template structure +- **"Update README"** → Validate against checklist and suggest missing sections +- **"Review my sample"** → Run full validation report +- **"Add authentication"** → Suggest proper patterns and documentation requirements +- **"Deploy to Azure"** → Check for deployment documentation and Azure Bot setup + +### Files to Monitor +- Any `README.md` in sample directories +- Configuration files: + - C#: `appsettings.json`, `appsettings.Development.json` + - Python: `.env`, `config.py`, `settings.py` + - JavaScript/TypeScript: `.env`, `config.js`, `config.json` +- Source files: + - C#: `*.cs`, `*.csx` + - Python: `*.py` + - JavaScript: `*.js`, `*.mjs` + - TypeScript: `*.ts` +- Project files: + - C#: `*.csproj`, `launchSettings.json` + - Python: `requirements.txt`, `pyproject.toml` + - JavaScript/TypeScript: `package.json`, `tsconfig.json` +- `manifest.json` in `appManifest/` folders +- `.gitignore` files in sample directories + +### Integration with Existing Rules +- This rule **extends** Rule 1 (Kairo check) and Rule 2 (Copyright headers) +- Apply all three rules together when reviewing sample code +- Prioritize security checks (no secrets) above all other validations