Skip to content

copilot-instructions.md

Latest commit

 

History

History
414 lines (341 loc) · 14.8 KB

copilot-instructions.md

File metadata and controls

414 lines (341 loc) · 14.8 KB
Raw

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):

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

Python Files (.py):

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.

JavaScript/TypeScript Files (.js, .ts, .mjs):

// 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 <auto-generated> or // <auto-generated />, .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):

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

using System;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace MyNamespace
{
    /// <summary>
    /// Class documentation
    /// </summary>
    public class MyClass
    {
        // Rest of the code...
    }
}

Python (.py):

# 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):

// 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+):

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

using System;
using System.Threading.Tasks;

namespace MyNamespace;

/// <summary>
/// Class documentation
/// </summary>
public class MyClass
{
    // Rest of the code...
}

Example with Top-Level Statements (C# 9+):

// 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., <<PLACEHOLDER>>, <<YOUR_API_KEY>>, 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 "<<YOUR_API_KEY>>"

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