````chatagent
---
name: AgentName                    # Unique identifier (PascalCase)
description: Brief description     # Used for routing/discovery
argument-hint: User input guide    # Instruction for users
tools: ['tool1', 'tool2', ...]    # Authorized capabilities
handoffs:                          # Inter-agent transitions
  - label: Button text
    agent: target_agent
    prompt: Handoff instructions
    send: true/false              # Auto-execute flag
---
{System Prompt}                    # Agent identity and role

<stopping_rules>
{Boundary conditions}              # Prevent scope creep
</stopping_rules>

<workflow>
{Step-by-step execution logic}     # Structured process
</workflow>

<guidelines>
{Specific operational rules}       # Style guides, standards
</guidelines>
````

---
name: Plan
description: Researches and outlines multi-step plans
tools: ['search', 'runSubagent', 'usages', 'problems', 'changes']
handoffs:
  - label: Start Implementation
    agent: agent
    prompt: Start implementation
---
You are a PLANNING AGENT, NOT an implementation agent.

<stopping_rules>
STOP IMMEDIATELY if you consider starting implementation.
Plans describe steps for the USER to execute later.
</stopping_rules>

<workflow>
## 1. Context gathering:
MANDATORY: Run #tool:runSubagent for autonomous research.

## 2. Present plan:
Follow <plan_style_guide> and pause for user feedback.

## 3. Handle feedback:
Restart <workflow> to refine plan based on new information.
</workflow>

---
description: Optional hover text in Chat view
applyTo: '**/*.cs'  # Glob pattern for file matching
---

# Instructions Body (Markdown)

- Write clear comments for each function
- Use PascalCase for class names
- Add newline before opening braces

---
applyTo: '**/*.cs'
description: C# coding conventions for this project
---

## Naming Conventions
- Use PascalCase for public members
- Use camelCase for private fields with `_` prefix

## Code Organization
- Group members: fields → constructors → properties → methods
- Add XML documentation for public APIs

Analyze the #file:src/services/OrderService.cs for:
1. Error handling patterns
2. Dependency injection usage
3. Async/await best practices

Compare with #file:src/services/BaseService.cs and suggest improvements.

<!-- File: .github/prompts/api-review.prompt.md -->

Review #selection for RESTful API compliance:

## Check:
- HTTP method semantics (GET/POST/PUT/DELETE)
- Status code appropriateness
- Request/response validation
- Error handling consistency

## Compare with:
- #file:docs/api-guidelines.md
- Existing patterns in #file:src/controllers/

Suggest improvements with code examples.

┌─────────────────────────────────────────────────────────────┐
│ HIGHEST PRIORITY: Explicit User Context                     │
│ - #file: references                                         │
│ - #symbol: references                                       │
│ - Selected code                                             │
│ - Attached images/errors                                    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ IMPLICIT CONTEXT: Current Environment                       │
│ - Active editor file                                        │
│ - Open tabs                                                 │
│ - Chat history (current session)                            │
│ - Cursor position/surrounding code                          │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ INSTRUCTIONS: Scoped Rules                                  │
│ - Matched .instructions.md (via applyTo patterns)           │
│ - Global copilot-instructions.md                            │
│ - Agent-specific guidelines                                 │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ SEMANTIC CONTEXT: RAG Retrieval                             │
│ - Vector search on codebase index                           │
│ - Semantic similarity matches                               │
│ - Cross-file relationship analysis                          │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ SYSTEM PROMPT: Base Capabilities                            │
│ - Model capabilities (GPT-4, Claude, etc.)                  │
│ - Base programming knowledge                                │
│ - General best practices                                    │
└─────────────────────────────────────────────────────────────┘

User prompt: "Optimize this function"
+ Selected code: function calculateTotal() {...}
+ .instructions.md: "Use LINQ for collections"
+ System knowledge: "Use loops for performance"

Result: Applies LINQ (per instructions) > generic loop optimization

Code Embeddings:
├── Function signatures
├── Class definitions
├── Comment/documentation text
├── Variable names
├── Import/dependency relationships
└── Code structure patterns

1. Query Vectorization
   User prompt → Vector embedding (e.g., 1536 dimensions)

2. Similarity Computation
   Compare query vector with code embedding vectors
   Cosine similarity: sim(A,B) = (A·B) / (|A||B|)

3. Ranking & Retrieval
   Top-K files with highest semantic similarity
   Typical K = 5-20 files depending on context window

4. Context Augmentation
   Retrieved files added to prompt context
   Prioritized by relevance score

Agent receives prompt
    ↓
Checks available tools: ['semantic_search', 'read_file', 'grep_search']
    ↓
Decision logic:
  - Concept-based query → semantic_search
  - Exact pattern search → grep_search
  - Known file location → read_file
    ↓
RAG retrieves relevant code
    ↓
Agent synthesizes response with retrieved context
    ↓
Cites sources in response (file paths, line numbers)

<workflow>
## 1. Context gathering and research:
MANDATORY: Run #tool:runSubagent tool, instructing it to:
  - Use semantic_search for conceptual understanding
  - Follow with grep_search for specific patterns
  - Read identified files with targeted queries

Stop research at 80% confidence threshold.
</workflow>

┌─────────────────────────────────────────────────────────┐
│                    AI Agent (Copilot)                   │
└────────────────────────┬────────────────────────────────┘
                         │
                         │ MCP Client
                         ↓
┌─────────────────────────────────────────────────────────┐
│              Model Context Protocol (MCP)               │
│  ┌─────────────┬──────────────┬─────────────────────┐  │
│  │   Tools     │  Resources   │      Prompts        │  │
│  │ (Actions)   │ (Data Access)│  (Templates)        │  │
│  └─────────────┴──────────────┴─────────────────────┘  │
└────────────────────────┬────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ↓                ↓                ↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ MCP Server 1 │ │ MCP Server 2 │ │ MCP Server N │
│  (GitHub)    │ │ (Azure Docs) │ │  (Dataverse) │
└──────────────┘ └──────────────┘ └──────────────┘

{
  "mcpServers": {
    "github": {
      "command": "mcp-server-github",
      "args": ["--token", "${GITHUB_TOKEN}"],
      "disabled": false
    },
    "microsoft-docs": {
      "type": "sse",
      "url": "https://mcp-docs.microsoft.com",
      "disabled": false
    }
  }
}

# In .agent.md
tools: [
  'search',                              # Built-in VS Code tool
  'github/github-mcp-server/get_issue',  # MCP tool from GitHub server
  'microsoft-docs/docs_search'           # MCP tool from Microsoft server
]

Agent determines: "Need to search Microsoft docs"
    ↓
Checks MCP servers for relevant tools
    ↓
Finds: microsoft-docs/docs_search
    ↓
Requests user approval (first use)
    ↓
Invokes tool with parameters
    ↓
Receives structured response
    ↓
Integrates into agent response

User types: #mcp:github/pr-review
    ↓
MCP server provides template:
"""
Review #pr:123 for:
- Code quality issues
- Security vulnerabilities
- Breaking changes

Format: {template_structure}
"""
    ↓
User fills in PR number → Agent executes

---
applyTo: '**'
---

You have access to MCP tools:
- `microsoft_docs_search`: Query official Microsoft documentation
- `github/get_issue`: Retrieve GitHub issue details

For questions about Microsoft technologies, ALWAYS use microsoft_docs_search
before relying on training data.

<!-- scp-mcp-context.md -->
# Security Copilot MCP Tools Context

When building agents, use these MCP tools:
1. `get_agent_skills`: List available Security Copilot skills
2. `generate_agent_yaml`: Create agent definition from description
3. `deploy_agent`: Deploy agent to Security Copilot

Workflow:
1. Describe intent → generate_agent_yaml
2. Review YAML → iterate with user
3. Finalize → deploy_agent

Priority  Source Type              Scope         Override Power
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1         User Explicit Context     Single prompt    Overrides all
          (#file, #symbol, selection)

2         Agent Stopping Rules      Agent session    Overrides workflows
          (behavioral boundaries)

3         Targeted Instructions     File pattern     Overrides global
          (.instructions.md + applyTo)

4         Global Instructions       Workspace        Overrides system
          (copilot-instructions.md)

5         Agent Guidelines          Agent instance   Overrides generic
          (<workflow>, <guidelines>)

6         MCP Prompt Templates      Tool-specific    Overrides generic
          (from MCP servers)

7         RAG Retrieved Context     Semantic match   Augments knowledge
          (vector search results)

8         Chat History              Session          Provides continuity
          (previous conversation)

9         System Prompt             Model base       Foundational rules
          (model capabilities)

System: "Use snake_case for Python"
Global .instructions.md: "Use camelCase for consistency"
File-specific .instructions.md (applyTo: '**/*.py'): "Use snake_case per PEP8"

Result: snake_case (file-specific wins over global)

Agent stopping rule: "STOP if attempting file edits"
User prompt: "Edit this file to add logging"

Result: Agent refuses and suggests handoff to implementation agent
        (stopping rules protect agent integrity)

RAG retrieves: Old code pattern (deprecated approach)
.instructions.md: "Use new async/await pattern"

Result: Copilot suggests async/await pattern with reference to instructions
        (instructions guide interpretation of retrieved code)

FINAL CONTEXT for `src/services/PaymentService.cs`:

[System Prompt]
You are GitHub Copilot, an AI programming assistant...

[Global Instructions from copilot-instructions.md]
- Follow SOLID principles
- Write unit tests for business logic

[C# Instructions from .github/instructions/csharp.instructions.md]
- Use PascalCase for public members
- Add XML documentation

[Agent Guidelines from CodeReviewer.agent.md]
<stopping_rules>
STOP if attempting to fix code—only document issues.
</stopping_rules>

[RAG Retrieved Context]
File: src/services/OrderService.cs (similar payment logic)
[...code snippet...]

[User Query]
"Review the ProcessPayment method"

┌─────────────────────────────────────────────────────────────┐
│ 1. Plan Agent                                               │
│    - Tools: semantic_search, runSubagent                    │
│    - Context: .instructions.md, RAG                         │
│    - Output: Structured plan in plan.prompt.md             │
└────────────────────┬────────────────────────────────────────┘
                     │ Handoff: #prompt:plan-implementation.prompt.md
                     ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. Implementation Agent                                     │
│    - Tools: replace_string_in_file, run_in_terminal        │
│    - Context: Plan + .instructions.md + RAG                │
│    - Output: Code changes + test files                     │
└────────────────────┬────────────────────────────────────────┘
                     │ Handoff: "Run tests"
                     ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Test Agent                                               │
│    - Tools: run_in_terminal, get_errors                    │
│    - Context: Test results + error logs                    │
│    - Output: Test report + fix suggestions                 │
└─────────────────────────────────────────────────────────────┘

# Pseudo-code for agent logic

def search_authentication():
    # 1. Semantic Search (RAG)
    semantic_results = semantic_search(
        query="authentication login user validation",
        max_results=10
    )

    # 2. Validate with grep_search
    confirmed_files = []
    for file in semantic_results:
        if grep_search(
            query="authenticate|login|verify",
            file=file,
            isRegexp=True
        ):
            confirmed_files.append(file)

    # 3. Read relevant files
    code_snippets = []
    for file in confirmed_files[:5]:  # Limit token usage
        content = read_file(file)
        code_snippets.append({
            'file': file,
            'content': extract_auth_functions(content)
        })

    # 4. Synthesize response
    return f"""
    Found authentication in {len(confirmed_files)} files:

    {format_findings(code_snippets)}

    Common patterns:
    - JWT token validation
    - Password hashing with bcrypt
    - OAuth2 integration

    References: {list_file_paths(confirmed_files)}
    """

User: "How do I create an Azure Storage account with CLI?"
    ↓
Agent checks MCP tools: microsoft_docs_search available
    ↓
Agent calls: microsoft_docs_search(query="Azure Storage account CLI create")
    ↓
MCP returns:
{
  "results": [
    {
      "title": "Quickstart: Create storage account",
      "url": "https://learn.microsoft.com/azure/storage/...",
      "excerpt": "Use az storage account create to..."
    }
  ]
}
    ↓
Agent fetches full content: microsoft_docs_fetch(url=...)
    ↓
Agent synthesizes:
"""
To create an Azure Storage account using CLI:

```bash
az storage account create \
  --name mystorageaccount \
  --resource-group myresourcegroup \
  --location eastus \
  --sku Standard_LRS

### 6.4 Context-Aware File Generation

**Use Case:** Generate code matching project conventions

using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

namespace MyApp.Services
{
    /// <summary>
    /// Service for managing order operations.
    /// </summary>
    public interface IOrderService
    {
        Task<Order> GetOrderAsync(int orderId);
    }

    public class OrderService : IOrderService
    {
        private readonly ILogger<OrderService> _logger;
        private readonly IOrderRepository _repository;

        public OrderService(
            ILogger<OrderService> logger,
            IOrderRepository repository)
        {
            _logger = logger;
            _repository = repository;
        }

        // Implementation follows...
    }
}

---

## 7. Code Examples and Configuration Patterns

### 7.1 Complete .instructions.md Example

```markdown
<!-- .github/instructions/typescript.instructions.md -->
---
description: TypeScript coding standards for React components
applyTo: 'src/**/*.tsx'
---

# React Component Guidelines

## Naming Conventions
- Use PascalCase for component files: `UserProfile.tsx`
- Use camelCase for utility files: `formatDate.ts`

## Component Structure
```typescript
// 1. Imports (grouped: React → third-party → local)
import React, { useState, useEffect } from 'react';
import { Button } from '@mui/material';
import { useAuth } from '@/hooks/useAuth';

// 2. Type definitions
interface UserProfileProps {
  userId: string;
  onUpdate?: (user: User) => void;
}

// 3. Component
export const UserProfile: React.FC<UserProfileProps> = ({ userId, onUpdate }) => {
  // 3.1 Hooks (useState → useEffect → custom hooks)
  const [user, setUser] = useState<User | null>(null);
  const { isAuthenticated } = useAuth();

  // 3.2 Event handlers
  const handleUpdate = () => { /* ... */ };

  // 3.3 Render
  return <div>{/* ... */}</div>;
};

<!-- .github/prompts/bug-investigation.prompt.md -->

Investigate bug: [BUG_DESCRIPTION]

## Error Context

## Investigation Steps
1. Search for error message: Use semantic_search
2. Check recent changes: Review #changes
3. Examine test failures: Check #testFailure
4. Review related code: #file:[AFFECTED_FILE]

## Analysis
- Root cause hypothesis
- Affected components
- Reproduction steps
- Suggested fix approach

## Next Steps
- [ ] Verify fix in isolation
- [ ] Add regression test
- [ ] Update error handling

// .mcp.json (User-level MCP configuration)
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      },
      "disabled": false
    },

    "microsoft-docs": {
      "type": "sse",
      "url": "https://mcp-docs-server.microsoft.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${MS_DOCS_TOKEN}"
      },
      "disabled": false
    },

    "azure-resources": {
      "command": "azure-mcp-server",
      "args": ["--subscription", "${AZURE_SUBSCRIPTION_ID}"],
      "disabled": false
    }
  },

  "mcpToolApprovals": {
    "github/get_issue": "always",
    "microsoft-docs/docs_search": "always",
    "azure-resources/deploy": "prompt"
  }
}

<!-- InfoGatherer.agent.md -->
````chatagent
---
name: InfoGatherer
description: Researches codebases and synthesizes findings into reports
argument-hint: Describe what information to gather (e.g., "Find all API endpoints")
tools: [
  'semantic_search',
  'grep_search',
  'read_file',
  'list_dir',
  'fetch_webpage',
  'github/github-mcp-server/get_issue',
  'microsoft-docs/docs_search'
]
handoffs:
  - label: Generate Documentation
    agent: agent
    prompt: '#createFile Create a report from the gathered information'
---
You are an INFORMATION GATHERING AGENT specializing in codebase research and analysis.

Your role is to autonomously search, read, and synthesize information from multiple sources, NOT to implement changes.

<stopping_rules>
STOP IMMEDIATELY if you attempt to edit files, run terminal commands, or make code changes.

If you identify areas needing changes, DOCUMENT them for handoff—do not implement.
</stopping_rules>

<workflow>
## 1. Query Analysis
- Parse user request to identify key concepts
- Determine information sources: codebase, docs, issues
- Set confidence threshold (target: 90%)

## 2. Multi-Source Research
Execute searches in parallel:

### A. Codebase Search (RAG)

### B. Documentation Search (MCP)
If query relates to frameworks/technologies:

### C. Issue Tracker (MCP)
If query involves bugs/features:

## 3. Synthesis
Organize findings:
```markdown
## Summary (2-3 sentences)

## Detailed Findings
### Source 1: [Codebase]
- Location: #file:path/to/file.ts:123
- Key points: ...

### Source 2: [Documentation]
- Reference: [Title](url)
- Key points: ...

### Source 3: [Issues]
- Issue #123: ...
- Related: #456, #789

## Patterns Identified
- Common approach: ...
- Variations: ...
- Edge cases: ...

## Recommendations
1. [Actionable suggestion]
2. [Alternative approach]

## References
- [List of all sources consulted]