Merge branch 'main' into MCP-M365-Agents

2026-02-22 11:25:13 +00:00 · 2026-01-09 07:03:26 -10:00
parent b9763bda06 fcfa14e758
commit 6079d04bd2
26 changed files with 3502 additions and 24 deletions
--- a/prompts/devops-rollout-plan.prompt.md
+++ b/prompts/devops-rollout-plan.prompt.md
@@ -0,0 +1,118 @@
+---
+agent: 'agent'
+description: 'Generate comprehensive rollout plans with preflight checks, step-by-step deployment, verification signals, rollback procedures, and communication plans for infrastructure and application changes'
+tools: ['codebase', 'terminalCommand', 'search', 'githubRepo']
+---
+
+# DevOps Rollout Plan Generator
+
+Your goal is to create a comprehensive, production-ready rollout plan for infrastructure or application changes.
+
+## Input Requirements
+
+Gather these details before generating the plan:
+
+### Change Description
+- What's changing (infrastructure, application, configuration)
+- Version or state transition (from/to)
+- Problem solved or feature added
+
+### Environment Details
+- Target environment (dev, staging, production, all)
+- Infrastructure type (Kubernetes, VMs, serverless, containers)
+- Affected services and dependencies
+- Current capacity and scale
+
+### Constraints & Requirements
+- Acceptable downtime window
+- Change window restrictions
+- Approval requirements
+- Regulatory or compliance considerations
+
+### Risk Assessment
+- Blast radius of change
+- Data migrations or schema changes
+- Rollback complexity and safety
+- Known risks
+
+## Output Format
+
+Generate a structured rollout plan with these sections:
+
+### 1. Executive Summary
+- What, why, when, duration
+- Risk level and rollback time
+- Affected systems and user impact
+- Expected downtime
+
+### 2. Prerequisites & Approvals
+- Required approvals (technical lead, security, compliance, business)
+- Required resources (capacity, backups, monitoring, rollback automation)
+- Pre-deployment backups
+
+### 3. Preflight Checks
+- Infrastructure health validation
+- Application health baseline
+- Dependency availability
+- Monitoring baseline metrics
+- Go/no-go decision checklist
+
+### 4. Step-by-Step Rollout Procedure
+**Phases**: Pre-deployment, deployment, progressive verification
+- Specific commands for each step
+- Validation after each step
+- Duration estimates
+
+### 5. Verification Signals
+**Immediate** (0-2 min): Deployment success, pods/containers started, health checks passing
+**Short-term** (2-5 min): Application responding, error rates acceptable, latency normal
+**Medium-term** (5-15 min): Sustained metrics, stable connections, integrations working
+**Long-term** (15+ min): No degradation, capacity healthy, business metrics normal
+
+### 6. Rollback Procedure
+**Decision Criteria**: When to initiate rollback
+**Rollback Steps**: Automated, infrastructure revert, or full restore
+**Post-Rollback Verification**: Confirm system health restored
+**Communication**: Stakeholder notification
+
+### 7. Communication Plan
+- Pre-deployment (T-24h): Schedule and impact notice
+- Deployment start: Commencement notice
+- Progress updates: Status every X minutes
+- Completion: Success confirmation
+- Rollback (if needed): Issue notification
+
+**Stakeholder Matrix**: Who to notify, when, via what method, with what content
+
+### 8. Post-Deployment Tasks
+- Immediate (1h): Verify criteria met, review logs
+- Short-term (24h): Monitor metrics, review errors
+- Medium-term (1 week): Post-deployment review, lessons learned
+
+### 9. Contingency Plans
+Scenarios: Partial failure, performance degradation, data inconsistency, dependency failure
+For each: Symptoms, response, timeline
+
+### 10. Contact Information
+- Primary and secondary on-call
+- Escalation path
+- Emergency contacts (infrastructure, security, database, networking)
+
+## Plan Customization
+
+Adapt based on:
+- **Infrastructure Type**: Kubernetes, VMs, serverless, databases
+- **Risk Level**: Low (simplified), medium (standard), high (additional gates)
+- **Change Type**: Code deployment, infrastructure, configuration, data migration
+- **Environment**: Production (full plan), staging (simplified), development (minimal)
+
+## Remember
+
+- Always have a tested rollback plan
+- Communicate early and often
+- Monitor metrics, not just logs
+- Document everything
+- Learn from each deployment
+- Never deploy on Friday afternoon (unless critical)
+- Never skip verification steps
+- Never assume "it should work"
--- a/prompts/dotnet-upgrade.prompt.md
+++ b/prompts/dotnet-upgrade.prompt.md
@@ -1,115 +1,114 @@
 ---
 name: ".NET Upgrade Analysis Prompts"
 description: "Ready-to-use prompts for comprehensive .NET framework upgrade analysis and execution"
-prompts:
 ---
  # Project Discovery & Assessment
  - name: "Project Classification Analysis"
    prompt: "Identify all projects in the solution and classify them by type (`.NET Framework`, `.NET Core`, `.NET Standard`). Analyze each `.csproj` for its current `TargetFramework` and SDK usage."
-  
+
  - name: "Dependency Compatibility Review"
    prompt: "Review external and internal dependencies for framework compatibility. Determine the upgrade complexity based on dependency graph depth."
-  
+
  - name: "Legacy Package Detection"
    prompt: "Identify legacy `packages.config` projects needing migration to `PackageReference` format."

  # Upgrade Strategy & Sequencing
  - name: "Project Upgrade Ordering"
    prompt: "Recommend a project upgrade order from least to most dependent components. Suggest how to isolate class library upgrades before API or Azure Function migrations."
-  
+
  - name: "Incremental Strategy Planning"
    prompt: "Propose an incremental upgrade strategy with rollback checkpoints. Evaluate the use of **Upgrade Assistant** or **manual upgrades** based on project structure."
-  
+
  - name: "Progress Tracking Setup"
    prompt: "Generate an upgrade checklist for tracking build, test, and deployment readiness across all projects."

  # Framework Targeting & Code Adjustments
  - name: "Target Framework Selection"
    prompt: "Suggest the correct `TargetFramework` for each project (e.g., `net8.0`). Review and update deprecated SDK or build configurations."
-  
+
  - name: "Code Modernization Analysis"
    prompt: "Identify code patterns needing modernization (e.g., `WebHostBuilder` → `HostBuilder`). Suggest replacements for deprecated .NET APIs and third-party libraries."
-  
+
  - name: "Async Pattern Conversion"
    prompt: "Recommend conversion of synchronous calls to async where appropriate for improved performance and scalability."

  # NuGet & Dependency Management
  - name: "Package Compatibility Analysis"
    prompt: "Analyze outdated or incompatible NuGet packages and suggest compatible versions. Identify third-party libraries that lack .NET 8 support and provide migration paths."
-  
+
  - name: "Shared Dependency Strategy"
    prompt: "Recommend strategies for handling shared dependency upgrades across projects. Evaluate usage of legacy packages and suggest alternatives in Microsoft-supported namespaces."
-  
+
  - name: "Transitive Dependency Review"
    prompt: "Review transitive dependencies and potential version conflicts after upgrade. Suggest resolution strategies for dependency conflicts."

  # CI/CD & Build Pipeline Updates
  - name: "Pipeline Configuration Analysis"
    prompt: "Analyze YAML build definitions for SDK version pinning and recommend updates. Suggest modifications for `UseDotNet@2` and `NuGetToolInstaller` tasks."
-  
+
  - name: "Build Pipeline Modernization"
    prompt: "Generate updated build pipeline snippets for .NET 8 migration. Recommend validation builds on feature branches before merging to main."
-  
+
  - name: "CI Automation Enhancement"
    prompt: "Identify opportunities to automate test and build verification in CI pipelines. Suggest strategies for continuous integration validation."

  # Testing & Validation
  - name: "Build Validation Strategy"
    prompt: "Propose validation checks to ensure the upgraded solution builds and runs successfully. Recommend automated test execution for unit and integration suites post-upgrade."
-  
+
  - name: "Service Integration Verification"
    prompt: "Generate validation steps to verify logging, telemetry, and service connectivity. Suggest strategies for verifying backward compatibility and runtime behavior."
-  
+
  - name: "Deployment Readiness Check"
    prompt: "Recommend UAT deployment verification steps before production rollout. Create comprehensive testing scenarios for upgraded components."

  # Breaking Change Analysis
  - name: "API Deprecation Detection"
    prompt: "Identify deprecated APIs or removed namespaces between target versions. Suggest automated scanning using `.NET Upgrade Assistant` and API Analyzer."
-  
+
  - name: "API Replacement Strategy"
    prompt: "Recommend replacement APIs or libraries for known breaking areas. Review configuration changes such as `Startup.cs` → `Program.cs` refactoring."
-  
+
  - name: "Regression Testing Focus"
    prompt: "Suggest regression testing scenarios focused on upgraded API endpoints or services. Create test plans for critical functionality validation."

  # Version Control & Commit Strategy
  - name: "Branching Strategy Planning"
    prompt: "Recommend branching strategy for safe upgrade with rollback capability. Generate commit templates for partial and complete project upgrades."
-  
+
  - name: "PR Structure Optimization"
    prompt: "Suggest best practices for creating structured PRs (`Upgrade to .NET [Version]`). Identify tagging strategies for PRs involving breaking changes."
-  
+
  - name: "Code Review Guidelines"
    prompt: "Recommend peer review focus areas (build, test, and dependency validation). Create checklists for effective upgrade reviews."

  # Documentation & Communication
  - name: "Upgrade Documentation Strategy"
    prompt: "Suggest how to document each project's framework change in the PR. Propose automated release note generation summarizing upgrades and test results."
-  
+
  - name: "Stakeholder Communication"
    prompt: "Recommend communicating version upgrades and migration timelines to consumers. Generate documentation templates for dependency updates and validation results."
-  
+
  - name: "Progress Tracking Systems"
    prompt: "Suggest maintaining an upgrade summary dashboard or markdown checklist. Create templates for tracking upgrade progress across multiple projects."

  # Tools & Automation
  - name: "Upgrade Tool Selection"
    prompt: "Recommend when and how to use: `.NET Upgrade Assistant`, `dotnet list package --outdated`, `dotnet migrate`, and `graph.json` dependency visualization."
-  
+
  - name: "Analysis Script Generation"
    prompt: "Generate scripts or prompts for analyzing dependency graphs before upgrading. Propose AI-assisted prompts for Copilot to identify upgrade issues automatically."
-  
+
  - name: "Multi-Repository Validation"
    prompt: "Suggest how to validate automation output across multiple repositories. Create standardized validation workflows for enterprise-scale upgrades."

  # Final Validation & Delivery
  - name: "Final Solution Validation"
    prompt: "Generate validation steps to confirm the final upgraded solution passes all validation checks. Suggest production deployment verification steps post-upgrade."
-  
+
  - name: "Deployment Readiness Confirmation"
    prompt: "Recommend generating final test results and build artifacts. Create a checklist summarizing completion across projects (builds/tests/deployment)."
-  
+
  - name: "Release Documentation"
    prompt: "Generate a release note summarizing framework changes and CI/CD updates. Create comprehensive upgrade summary documentation."

--- a/prompts/typespec-api-operations.prompt.md
+++ b/prompts/typespec-api-operations.prompt.md
@@ -0,0 +1,421 @@
+---
+mode: 'agent'
+tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
+description: 'Add GET, POST, PATCH, and DELETE operations to a TypeSpec API plugin with proper routing, parameters, and adaptive cards'
+model: 'gpt-4.1'
+tags: [typespec, m365-copilot, api-plugin, rest-operations, crud]
+---
+
+# Add TypeSpec API Operations
+
+Add RESTful operations to an existing TypeSpec API plugin for Microsoft 365 Copilot.
+
+## Adding GET Operations
+
+### Simple GET - List All Items
+```typescript
+/**
+ * List all items.
+ */
+@route("/items")
+@get op listItems(): Item[];
+```
+
+### GET with Query Parameter - Filter Results
+```typescript
+/**
+ * List items filtered by criteria.
+ * @param userId Optional user ID to filter items
+ */
+@route("/items")
+@get op listItems(@query userId?: integer): Item[];
+```
+
+### GET with Path Parameter - Get Single Item
+```typescript
+/**
+ * Get a specific item by ID.
+ * @param id The ID of the item to retrieve
+ */
+@route("/items/{id}")
+@get op getItem(@path id: integer): Item;
+```
+
+### GET with Adaptive Card
+```typescript
+/**
+ * List items with adaptive card visualization.
+ */
+@route("/items")
+@card(#{
+  dataPath: "$",
+  title: "$.title",
+  file: "item-card.json"
+})
+@get op listItems(): Item[];
+```
+
+**Create the Adaptive Card** (`appPackage/item-card.json`):
+```json
+{
+  "type": "AdaptiveCard",
+  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+  "version": "1.5",
+  "body": [
+    {
+      "type": "Container",
+      "$data": "${$root}",
+      "items": [
+        {
+          "type": "TextBlock",
+          "text": "**${if(title, title, 'N/A')}**",
+          "wrap": true
+        },
+        {
+          "type": "TextBlock",
+          "text": "${if(description, description, 'N/A')}",
+          "wrap": true
+        }
+      ]
+    }
+  ],
+  "actions": [
+    {
+      "type": "Action.OpenUrl",
+      "title": "View Details",
+      "url": "https://example.com/items/${id}"
+    }
+  ]
+}
+```
+
+## Adding POST Operations
+
+### Simple POST - Create Item
+```typescript
+/**
+ * Create a new item.
+ * @param item The item to create
+ */
+@route("/items")
+@post op createItem(@body item: CreateItemRequest): Item;
+
+model CreateItemRequest {
+  title: string;
+  description?: string;
+  userId: integer;
+}
+```
+
+### POST with Confirmation
+```typescript
+/**
+ * Create a new item with confirmation.
+ */
+@route("/items")
+@post
+@capabilities(#{
+  confirmation: #{
+    type: "AdaptiveCard",
+    title: "Create Item",
+    body: """
+    Are you sure you want to create this item?
+      * **Title**: {{ function.parameters.item.title }}
+      * **User ID**: {{ function.parameters.item.userId }}
+    """
+  }
+})
+op createItem(@body item: CreateItemRequest): Item;
+```
+
+## Adding PATCH Operations
+
+### Simple PATCH - Update Item
+```typescript
+/**
+ * Update an existing item.
+ * @param id The ID of the item to update
+ * @param item The updated item data
+ */
+@route("/items/{id}")
+@patch op updateItem(
+  @path id: integer,
+  @body item: UpdateItemRequest
+): Item;
+
+model UpdateItemRequest {
+  title?: string;
+  description?: string;
+  status?: "active" | "completed" | "archived";
+}
+```
+
+### PATCH with Confirmation
+```typescript
+/**
+ * Update an item with confirmation.
+ */
+@route("/items/{id}")
+@patch
+@capabilities(#{
+  confirmation: #{
+    type: "AdaptiveCard",
+    title: "Update Item",
+    body: """
+    Updating item #{{ function.parameters.id }}:
+      * **Title**: {{ function.parameters.item.title }}
+      * **Status**: {{ function.parameters.item.status }}
+    """
+  }
+})
+op updateItem(
+  @path id: integer,
+  @body item: UpdateItemRequest
+): Item;
+```
+
+## Adding DELETE Operations
+
+### Simple DELETE
+```typescript
+/**
+ * Delete an item.
+ * @param id The ID of the item to delete
+ */
+@route("/items/{id}")
+@delete op deleteItem(@path id: integer): void;
+```
+
+### DELETE with Confirmation
+```typescript
+/**
+ * Delete an item with confirmation.
+ */
+@route("/items/{id}")
+@delete
+@capabilities(#{
+  confirmation: #{
+    type: "AdaptiveCard",
+    title: "Delete Item",
+    body: """
+    ⚠️ Are you sure you want to delete item #{{ function.parameters.id }}?
+    This action cannot be undone.
+    """
+  }
+})
+op deleteItem(@path id: integer): void;
+```
+
+## Complete CRUD Example
+
+### Define the Service and Models
+```typescript
+@service
+@server("https://api.example.com")
+@actions(#{
+  nameForHuman: "Items API",
+  descriptionForHuman: "Manage items",
+  descriptionForModel: "Read, create, update, and delete items"
+})
+namespace ItemsAPI {
+  
+  // Models
+  model Item {
+    @visibility(Lifecycle.Read)
+    id: integer;
+    
+    userId: integer;
+    title: string;
+    description?: string;
+    status: "active" | "completed" | "archived";
+    
+    @format("date-time")
+    createdAt: utcDateTime;
+    
+    @format("date-time")
+    updatedAt?: utcDateTime;
+  }
+
+  model CreateItemRequest {
+    userId: integer;
+    title: string;
+    description?: string;
+  }
+
+  model UpdateItemRequest {
+    title?: string;
+    description?: string;
+    status?: "active" | "completed" | "archived";
+  }
+
+  // Operations
+  @route("/items")
+  @card(#{ dataPath: "$", title: "$.title", file: "item-card.json" })
+  @get op listItems(@query userId?: integer): Item[];
+
+  @route("/items/{id}")
+  @card(#{ dataPath: "$", title: "$.title", file: "item-card.json" })
+  @get op getItem(@path id: integer): Item;
+
+  @route("/items")
+  @post
+  @capabilities(#{
+    confirmation: #{
+      type: "AdaptiveCard",
+      title: "Create Item",
+      body: "Creating: **{{ function.parameters.item.title }}**"
+    }
+  })
+  op createItem(@body item: CreateItemRequest): Item;
+
+  @route("/items/{id}")
+  @patch
+  @capabilities(#{
+    confirmation: #{
+      type: "AdaptiveCard",
+      title: "Update Item",
+      body: "Updating item #{{ function.parameters.id }}"
+    }
+  })
+  op updateItem(@path id: integer, @body item: UpdateItemRequest): Item;
+
+  @route("/items/{id}")
+  @delete
+  @capabilities(#{
+    confirmation: #{
+      type: "AdaptiveCard",
+      title: "Delete Item",
+      body: "⚠️ Delete item #{{ function.parameters.id }}?"
+    }
+  })
+  op deleteItem(@path id: integer): void;
+}
+```
+
+## Advanced Features
+
+### Multiple Query Parameters
+```typescript
+@route("/items")
+@get op listItems(
+  @query userId?: integer,
+  @query status?: "active" | "completed" | "archived",
+  @query limit?: integer,
+  @query offset?: integer
+): ItemList;
+
+model ItemList {
+  items: Item[];
+  total: integer;
+  hasMore: boolean;
+}
+```
+
+### Header Parameters
+```typescript
+@route("/items")
+@get op listItems(
+  @header("X-API-Version") apiVersion?: string,
+  @query userId?: integer
+): Item[];
+```
+
+### Custom Response Models
+```typescript
+@route("/items/{id}")
+@delete op deleteItem(@path id: integer): DeleteResponse;
+
+model DeleteResponse {
+  success: boolean;
+  message: string;
+  deletedId: integer;
+}
+```
+
+### Error Responses
+```typescript
+model ErrorResponse {
+  error: {
+    code: string;
+    message: string;
+    details?: string[];
+  };
+}
+
+@route("/items/{id}")
+@get op getItem(@path id: integer): Item | ErrorResponse;
+```
+
+## Testing Prompts
+
+After adding operations, test with these prompts:
+
+**GET Operations:**
+- "List all items and show them in a table"
+- "Show me items for user ID 1"
+- "Get the details of item 42"
+
+**POST Operations:**
+- "Create a new item with title 'My Task' for user 1"
+- "Add an item: title 'New Feature', description 'Add login'"
+
+**PATCH Operations:**
+- "Update item 10 with title 'Updated Title'"
+- "Change the status of item 5 to completed"
+
+**DELETE Operations:**
+- "Delete item 99"
+- "Remove the item with ID 15"
+
+## Best Practices
+
+### Parameter Naming
+- Use descriptive parameter names: `userId` not `uid`
+- Be consistent across operations
+- Use optional parameters (`?`) for filters
+
+### Documentation
+- Add JSDoc comments to all operations
+- Describe what each parameter does
+- Document expected responses
+
+### Models
+- Use `@visibility(Lifecycle.Read)` for read-only fields like `id`
+- Use `@format("date-time")` for date fields
+- Use union types for enums: `"active" | "completed"`
+- Make optional fields explicit with `?`
+
+### Confirmations
+- Always add confirmations to destructive operations (DELETE, PATCH)
+- Show key details in confirmation body
+- Use warning emoji (⚠️) for irreversible actions
+
+### Adaptive Cards
+- Keep cards simple and focused
+- Use conditional rendering with `${if(..., ..., 'N/A')}`
+- Include action buttons for common next steps
+- Test data binding with actual API responses
+
+### Routing
+- Use RESTful conventions:
+  - `GET /items` - List
+  - `GET /items/{id}` - Get one
+  - `POST /items` - Create
+  - `PATCH /items/{id}` - Update
+  - `DELETE /items/{id}` - Delete
+- Group related operations in the same namespace
+- Use nested routes for hierarchical resources
+
+## Common Issues
+
+### Issue: Parameter not showing in Copilot
+**Solution**: Check parameter is properly decorated with `@query`, `@path`, or `@body`
+
+### Issue: Adaptive card not rendering
+**Solution**: Verify file path in `@card` decorator and check JSON syntax
+
+### Issue: Confirmation not appearing
+**Solution**: Ensure `@capabilities` decorator is properly formatted with confirmation object
+
+### Issue: Model property not appearing in response
+**Solution**: Check if property needs `@visibility(Lifecycle.Read)` or remove it if it should be writable
--- a/prompts/typespec-create-agent.prompt.md
+++ b/prompts/typespec-create-agent.prompt.md
@@ -0,0 +1,94 @@
+---
+mode: 'agent'
+tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
+description: 'Generate a complete TypeSpec declarative agent with instructions, capabilities, and conversation starters for Microsoft 365 Copilot'
+model: 'gpt-4.1'
+tags: [typespec, m365-copilot, declarative-agent, agent-development]
+---
+
+# Create TypeSpec Declarative Agent
+
+Create a complete TypeSpec declarative agent for Microsoft 365 Copilot with the following structure:
+
+## Requirements
+
+Generate a `main.tsp` file with:
+
+1. **Agent Declaration**
+   - Use `@agent` decorator with a descriptive name and description
+   - Name should be 100 characters or less
+   - Description should be 1,000 characters or less
+
+2. **Instructions**
+   - Use `@instructions` decorator with clear behavioral guidelines
+   - Define the agent's role, expertise, and personality
+   - Specify what the agent should and shouldn't do
+   - Keep under 8,000 characters
+
+3. **Conversation Starters**
+   - Include 2-4 `@conversationStarter` decorators
+   - Each with a title and example query
+   - Make them diverse and showcase different capabilities
+
+4. **Capabilities** (based on user needs)
+   - `WebSearch` - for web content with optional site scoping
+   - `OneDriveAndSharePoint` - for document access with URL filtering
+   - `TeamsMessages` - for Teams channel/chat access
+   - `Email` - for email access with folder filtering
+   - `People` - for organization people search
+   - `CodeInterpreter` - for Python code execution
+   - `GraphicArt` - for image generation
+   - `GraphConnectors` - for Copilot connector content
+   - `Dataverse` - for Dataverse data access
+   - `Meetings` - for meeting content access
+
+## Template Structure
+
+```typescript
+import "@typespec/http";
+import "@typespec/openapi3";
+import "@microsoft/typespec-m365-copilot";
+
+using TypeSpec.Http;
+using TypeSpec.M365.Copilot.Agents;
+
+@agent({
+  name: "[Agent Name]",
+  description: "[Agent Description]"
+})
+@instructions("""
+  [Detailed instructions about agent behavior, role, and guidelines]
+""")
+@conversationStarter(#{
+  title: "[Starter Title 1]",
+  text: "[Example query 1]"
+})
+@conversationStarter(#{
+  title: "[Starter Title 2]",
+  text: "[Example query 2]"
+})
+namespace [AgentName] {
+  // Add capabilities as operations here
+  op capabilityName is AgentCapabilities.[CapabilityType]<[Parameters]>;
+}
+```
+
+## Best Practices
+
+- Use descriptive, role-based agent names (e.g., "Customer Support Assistant", "Research Helper")
+- Write instructions in second person ("You are...")
+- Be specific about the agent's expertise and limitations
+- Include diverse conversation starters that showcase different features
+- Only include capabilities the agent actually needs
+- Scope capabilities (URLs, folders, etc.) when possible for better performance
+- Use triple-quoted strings for multi-line instructions
+
+## Examples
+
+Ask the user:
+1. What is the agent's purpose and role?
+2. What capabilities does it need?
+3. What knowledge sources should it access?
+4. What are typical user interactions?
+
+Then generate the complete TypeSpec agent definition.
--- a/prompts/typespec-create-api-plugin.prompt.md
+++ b/prompts/typespec-create-api-plugin.prompt.md
@@ -0,0 +1,167 @@
+---
+mode: 'agent'
+tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
+description: 'Generate a TypeSpec API plugin with REST operations, authentication, and Adaptive Cards for Microsoft 365 Copilot'
+model: 'gpt-4.1'
+tags: [typespec, m365-copilot, api-plugin, rest-api]
+---
+
+# Create TypeSpec API Plugin
+
+Create a complete TypeSpec API plugin for Microsoft 365 Copilot that integrates with external REST APIs.
+
+## Requirements
+
+Generate TypeSpec files with:
+
+### main.tsp - Agent Definition
+```typescript
+import "@typespec/http";
+import "@typespec/openapi3";
+import "@microsoft/typespec-m365-copilot";
+import "./actions.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.M365.Copilot.Agents;
+using TypeSpec.M365.Copilot.Actions;
+
+@agent({
+  name: "[Agent Name]",
+  description: "[Description]"
+})
+@instructions("""
+  [Instructions for using the API operations]
+""")
+namespace [AgentName] {
+  // Reference operations from actions.tsp
+  op operation1 is [APINamespace].operationName;
+}
+```
+
+### actions.tsp - API Operations
+```typescript
+import "@typespec/http";
+import "@microsoft/typespec-m365-copilot";
+
+using TypeSpec.Http;
+using TypeSpec.M365.Copilot.Actions;
+
+@service
+@actions(#{
+    nameForHuman: "[API Display Name]",
+    descriptionForModel: "[Model description]",
+    descriptionForHuman: "[User description]"
+})
+@server("[API_BASE_URL]", "[API Name]")
+@useAuth([AuthType]) // Optional
+namespace [APINamespace] {
+  
+  @route("[/path]")
+  @get
+  @action
+  op operationName(
+    @path param1: string,
+    @query param2?: string
+  ): ResponseModel;
+
+  model ResponseModel {
+    // Response structure
+  }
+}
+```
+
+## Authentication Options
+
+Choose based on API requirements:
+
+1. **No Authentication** (Public APIs)
+   ```typescript
+   // No @useAuth decorator needed
+   ```
+
+2. **API Key**
+   ```typescript
+   @useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">)
+   ```
+
+3. **OAuth2**
+   ```typescript
+   @useAuth(OAuth2Auth<[{
+     type: OAuth2FlowType.authorizationCode;
+     authorizationUrl: "https://oauth.example.com/authorize";
+     tokenUrl: "https://oauth.example.com/token";
+     refreshUrl: "https://oauth.example.com/token";
+     scopes: ["read", "write"];
+   }]>)
+   ```
+
+4. **Registered Auth Reference**
+   ```typescript
+   @useAuth(Auth)
+   
+   @authReferenceId("registration-id-here")
+   model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">
+   ```
+
+## Function Capabilities
+
+### Confirmation Dialog
+```typescript
+@capabilities(#{
+  confirmation: #{
+    type: "AdaptiveCard",
+    title: "Confirm Action",
+    body: """
+    Are you sure you want to perform this action?
+      * **Parameter**: {{ function.parameters.paramName }}
+    """
+  }
+})
+```
+
+### Adaptive Card Response
+```typescript
+@card(#{
+  dataPath: "$.items",
+  title: "$.title",
+  url: "$.link",
+  file: "cards/card.json"
+})
+```
+
+### Reasoning & Response Instructions
+```typescript
+@reasoning("""
+  Consider user's context when calling this operation.
+  Prioritize recent items over older ones.
+""")
+@responding("""
+  Present results in a clear table format with columns: ID, Title, Status.
+  Include a summary count at the end.
+""")
+```
+
+## Best Practices
+
+1. **Operation Names**: Use clear, action-oriented names (listProjects, createTicket)
+2. **Models**: Define TypeScript-like models for requests and responses
+3. **HTTP Methods**: Use appropriate verbs (@get, @post, @patch, @delete)
+4. **Paths**: Use RESTful path conventions with @route
+5. **Parameters**: Use @path, @query, @header, @body appropriately
+6. **Descriptions**: Provide clear descriptions for model understanding
+7. **Confirmations**: Add for destructive operations (delete, update critical data)
+8. **Cards**: Use for rich visual responses with multiple data items
+
+## Workflow
+
+Ask the user:
+1. What is the API base URL and purpose?
+2. What operations are needed (CRUD operations)?
+3. What authentication method does the API use?
+4. Should confirmations be required for any operations?
+5. Do responses need Adaptive Cards?
+
+Then generate:
+- Complete `main.tsp` with agent definition
+- Complete `actions.tsp` with API operations and models
+- Optional `cards/card.json` if Adaptive Cards are needed