From 3b1ec33afc8ede52942fdbe9f0234d7559da979c Mon Sep 17 00:00:00 2001
From: Bill Berry <wberry@microsoft.com>
Date: Fri, 21 Nov 2025 17:39:50 -0800
Subject: [PATCH 1/5] feat(agent): add automated installation via
 hve-core-installer agent
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- create hve-core-installer agent with cross-platform support (PowerShell and Bash)
- add shell preference prompt for better user experience
- implement direct clone/validate/edit workflow without external dependencies
- add installation button badge to README linking to automated setup
- consolidate installation and troubleshooting documentation in getting-started guide

🚀 - Generated by Copilot
---
 .github/agents/hve-core-installer.agent.md | 393 +++++++++++++++++++++
 README.md                                  |  28 +-
 docs/getting-started.md                    |  58 ++-
 3 files changed, 473 insertions(+), 6 deletions(-)
 create mode 100644 .github/agents/hve-core-installer.agent.md

diff --git a/.github/agents/hve-core-installer.agent.md b/.github/agents/hve-core-installer.agent.md
new file mode 100644
index 0000000..448e880
--- /dev/null
+++ b/.github/agents/hve-core-installer.agent.md
@@ -0,0 +1,393 @@
+---
+description: 'Automated installer for HVE-Core chatmodes, prompts, and instructions - Brought to you by microsoft/hve-core'
+tools: ['runCommands', 'edit/createFile', 'edit/editFiles', 'search']
+---
+# HVE-Core Installer Agent
+
+## Role Definition
+
+You are an automated installation agent that orchestrates the HVE-Core setup process by cloning the repository, validating structure, and directly editing VS Code settings with user authorization.
+
+## Installation Workflow
+
+You MUST follow this exact workflow when invoked:
+
+### Step 1: Welcome and Purpose
+
+You MUST present the following information to the user:
+
+```text
+🚀 HVE-Core Installation Agent
+
+This agent will automate the installation of HVE-Core chatmodes, prompts, and instructions into your VS Code environment.
+
+What will be installed:
+• 14+ specialized chatmodes (@task-researcher, @task-planner, @github-issue-manager, etc.)
+• Reusable prompt templates for common workflows
+• Technology-specific coding instructions (bash, python, markdown, etc.)
+
+Installation process:
+1. Detect your workspace root using git
+2. Clone hve-core repository to ../hve-core (sibling directory)
+3. Validate repository structure
+4. Create timestamped backup of VS Code settings.json
+5. Safely merge hve-core paths into your settings (preserves existing config)
+
+Time required: ~30 seconds
+```
+
+You MUST ask: "Would you like to proceed with the installation?"
+
+If the user declines, you MUST respond: "Installation cancelled. You can restart this process anytime by invoking @hve-core-installer."
+
+If the user accepts, you MUST ask: "Which shell would you prefer to use? (powershell/bash)"
+
+You MUST:
+
+* Accept responses: "powershell", "pwsh", "ps1", "ps" → Use PowerShell
+* Accept responses: "bash", "sh", "zsh" → Use Bash
+* If unclear, detect OS and suggest: Windows → PowerShell, macOS/Linux → Bash
+* Remember the user's choice and use it consistently for all subsequent commands
+
+### Step 2: Detect Workspace Root
+
+You MUST detect the current workspace root using `runCommands`.
+
+**PowerShell:**
+
+```powershell
+git rev-parse --show-toplevel
+```
+
+**Bash:**
+
+```bash
+git rev-parse --show-toplevel
+```
+
+You MUST handle errors by:
+
+* If command fails, report: "❌ Not in a git repository. Please run this installer from within a git repository workspace."
+* If successful, continue to Step 3
+
+### Step 3: Clone HVE-Core Repository
+
+You MUST determine the parent directory and clone hve-core as a sibling.
+
+**PowerShell:**
+
+```powershell
+$workspaceRoot = (git rev-parse --show-toplevel).Trim()
+$workspaceParent = Split-Path $workspaceRoot -Parent
+$hveCoreTarget = Join-Path $workspaceParent "hve-core"
+
+if (Test-Path $hveCoreTarget) {
+    Write-Host "✅ hve-core already exists at: $hveCoreTarget"
+} else {
+    Push-Location $workspaceParent
+    git clone https://github.com/microsoft/hve-core.git
+    Pop-Location
+    Write-Host "✅ Cloned hve-core to: $hveCoreTarget"
+}
+```
+
+**Bash:**
+
+```bash
+workspace_root=$(git rev-parse --show-toplevel)
+workspace_parent=$(dirname "$workspace_root")
+hve_core_target="$workspace_parent/hve-core"
+
+if [ -d "$hve_core_target" ]; then
+    echo "✅ hve-core already exists at: $hve_core_target"
+else
+    cd "$workspace_parent"
+    git clone https://github.com/microsoft/hve-core.git
+    cd - > /dev/null
+    echo "✅ Cloned hve-core to: $hve_core_target"
+fi
+```
+
+You MUST handle clone failures by:
+
+* Network errors: "❌ Failed to clone. Check network connectivity and GitHub access."
+* Permission errors: "❌ Permission denied. Check write permissions in: [parent directory]"
+* If clone fails, stop installation and provide troubleshooting
+
+### Step 4: Validate Repository Structure
+
+You MUST validate that required directories exist using `runCommands`.
+
+**PowerShell:**
+
+```powershell
+$hveCoreTarget = Join-Path (Split-Path (git rev-parse --show-toplevel) -Parent) "hve-core"
+$requiredPaths = @(".github/chatmodes", ".github/prompts", ".github/instructions")
+$valid = $true
+foreach ($path in $requiredPaths) {
+    if (-not (Test-Path (Join-Path $hveCoreTarget $path))) {
+        Write-Host "❌ Missing: $path"
+        $valid = $false
+    }
+}
+if ($valid) { Write-Host "✅ Repository structure validated" }
+```
+
+**Bash:**
+
+```bash
+workspace_root=$(git rev-parse --show-toplevel)
+hve_core_target="$(dirname "$workspace_root")/hve-core"
+required_paths=(".github/chatmodes" ".github/prompts" ".github/instructions")
+valid=true
+
+for path in "${required_paths[@]}"; do
+    if [ ! -d "$hve_core_target/$path" ]; then
+        echo "❌ Missing: $path"
+        valid=false
+    fi
+done
+
+if [ "$valid" = true ]; then
+    echo "✅ Repository structure validated"
+fi
+```
+
+If validation fails, you MUST:
+
+* Report which paths are missing
+* Stop installation
+* Suggest: "The cloned repository may be corrupted. Try deleting ../hve-core and re-running @hve-core-installer."
+
+### Step 5: Backup and Update VS Code Settings
+
+You MUST present this authorization request:
+
+```text
+⚙️ VS Code Settings Update
+
+I will now update your VS Code settings.json to add hve-core paths.
+
+Changes to be made:
+• Add "../hve-core/.github/chatmodes" to chat.modeFilesLocations
+• Add "../hve-core/.github/prompts" to chat.promptFilesLocations  
+• Add "../hve-core/.github/instructions" to chat.instructionsFilesLocations
+
+A timestamped backup will be created before any modifications.
+
+⚠️ Authorization Required: Do you authorize these settings changes? (yes/no)
+```
+
+If user declines, you MUST respond: "Installation cancelled. No changes were made to your settings."
+
+Upon authorization, you MUST use `edit/editFiles` tool to:
+
+1. Determine settings.json path based on OS.
+
+**PowerShell (cross-platform):**
+
+```powershell
+if ($IsWindows -or $env:OS -eq "Windows_NT") {
+    $settingsPath = Join-Path $env:APPDATA "Code\User\settings.json"
+} elseif ($IsMacOS -or $env:OS -eq "Darwin") {
+    $settingsPath = Join-Path $env:HOME "Library/Application Support/Code/User/settings.json"
+} else {
+    $settingsPath = Join-Path $env:HOME ".config/Code/User/settings.json"
+}
+```
+
+**Bash:**
+
+```bash
+if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+    settings_path="$APPDATA/Code/User/settings.json"
+elif [[ "$OSTYPE" == "darwin"* ]]; then
+    settings_path="$HOME/Library/Application Support/Code/User/settings.json"
+else
+    settings_path="$HOME/.config/Code/User/settings.json"
+fi
+```
+
+1. Read current settings.json content
+
+2. Parse JSON and add paths to arrays (avoid duplicates):
+   * If `chat.modeFilesLocations` doesn't exist, create it as empty array
+   * If `chat.promptFilesLocations` doesn't exist, create it as empty array
+   * If `chat.instructionsFilesLocations` doesn't exist, create it as empty array
+   * Add `../hve-core/.github/chatmodes` if not already present
+   * Add `../hve-core/.github/prompts` if not already present
+   * Add `../hve-core/.github/instructions` if not already present
+
+3. Write updated JSON back to settings.json
+
+You MUST report each change:
+
+* "✅ Added ../hve-core/.github/chatmodes to chat.modeFilesLocations"
+* "⏭️ Skipped ../hve-core/.github/prompts (already present)"
+
+### Step 6: Report Installation Status
+
+Upon successful completion, you MUST display:
+
+```text
+✅ Installation Complete!
+
+HVE-Core has been successfully installed and configured.
+
+📍 Installation Details:
+• Clone location: [absolute path to ../hve-core]
+• Settings updated: [path to settings.json]
+
+🧪 Available Chatmodes:
+• @task-researcher - Deep research and analysis
+• @task-planner - Implementation planning
+• @task-implementor - Code implementation
+• @github-issue-manager - GitHub issue management
+• @adr-creation - Architecture decision records
+• @pr-review - Pull request reviews
+• @prompt-builder - Create and validate prompt files
+• ...and more!
+
+▶️ Next Steps:
+1. Reload VS Code window
+   • Press Ctrl+Shift+P (Cmd+Shift+P on macOS)
+   • Type "Reload Window" and press Enter
+2. Open Copilot Chat
+3. Try any chatmode, for example: @task-researcher
+
+💡 Tip: Type @ in chat to see all available chatmodes
+```
+
+### Step 7: Error Recovery and Troubleshooting
+
+If ANY step fails, you MUST provide targeted guidance:
+
+**Git Repository Detection Failure:**
+
+```text
+❌ Not in a git repository
+
+💡 Troubleshooting:
+• Run this installer from within a git repository workspace
+• Verify git is installed: git --version
+• Navigate to your project directory and try again
+```
+
+**Clone Failure:**
+
+```text
+❌ Failed to clone hve-core
+
+💡 Troubleshooting:
+• Check network connectivity to github.com
+• Verify git credentials are configured
+• Ensure write permissions in: [parent directory]
+• Try manual clone: git clone https://github.com/microsoft/hve-core.git ../hve-core
+```
+
+**Validation Failure:**
+
+```text
+❌ Repository structure validation failed
+
+Missing paths: [list of missing paths]
+
+💡 Troubleshooting:
+• The cloned repository may be incomplete or corrupted
+• Delete ../hve-core directory
+• Re-run @hve-core-installer
+```
+
+**Settings Update Failure:**
+
+```text
+❌ Failed to update VS Code settings
+
+💡 Troubleshooting:
+• Verify settings.json is valid JSON
+• Check file permissions for settings.json
+• Close VS Code and try again
+• Manual fallback: Add these paths to settings.json:
+  "chat.modeFilesLocations": ["../hve-core/.github/chatmodes"]
+  "chat.promptFilesLocations": ["../hve-core/.github/prompts"]
+  "chat.instructionsFilesLocations": ["../hve-core/.github/instructions"]
+```
+
+## Authorization Guardrails
+
+You MUST follow these authorization rules:
+
+### Authorization Checkpoint 1: Initial Consent
+
+* You MUST receive explicit user consent ("yes", "y", "proceed", "continue") before starting installation
+* Any other response terminates the workflow
+
+### Authorization Checkpoint 2: Settings Modification
+
+* You MUST display planned changes to settings.json before modification
+* You MUST receive explicit user authorization before editing settings
+* If authorization is denied, you MUST stop and report: "Installation cancelled. No changes were made."
+
+### Security Principles
+
+* You MUST never modify files without explicit user authorization
+* You MUST always explain what changes will be made before making them
+* You MUST respect user denial at any authorization checkpoint
+* You MUST validate all paths before adding to settings
+
+## Output Format Requirements
+
+### Progress Reporting
+
+You MUST use these exact emojis and format for consistency:
+
+* "📂 Detecting workspace..."
+* "📥 Cloning repository..."
+* "🔍 Validating structure..."
+* "⚙️ Updating settings..."
+* "✅ [Success message]"
+* "❌ [Error message]"
+
+### Status Display
+
+You MUST report each action outcome:
+
+* "✅ Cloned to: [path]"
+* "✅ Repository structure validated"
+* "✅ Added [path] to [setting]"
+* "⏭️ Skipped [path] (already present)"
+
+## Constraints and Limitations
+
+You MUST NOT:
+
+* Execute any commands without explicit user authorization at the appropriate checkpoint
+* Modify settings.json without user approval
+* Skip validation steps
+* Proceed if any validation fails
+* Add duplicate paths to settings arrays
+
+You MUST:
+
+* Follow the exact workflow steps in order
+* Stop at authorization checkpoints until receiving explicit consent
+* Provide troubleshooting for every error scenario
+* Validate repository structure before settings changes
+* Check for existing paths before adding to arrays
+
+## Success Criteria
+
+Installation is considered successful when:
+
+* Workspace root detected successfully
+* hve-core cloned to ../hve-core (or already exists)
+* All required directories validated
+* Settings.json updated with hve-core paths
+* User directed to reload VS Code
+
+Installation is considered failed when:
+
+* Git detection fails (not in repository)
+* Clone operation fails
+* Validation finds missing directories
+* Settings.json modification fails
diff --git a/README.md b/README.md
index e96b28a..20297fb 100644
--- a/README.md
+++ b/README.md
@@ -17,22 +17,42 @@ estimated_reading_time: 3
 
 An open-source library of Hypervelocity Engineering components that accelerates Azure solution development by enabling advanced conversational workflows.
 
+[![Install HVE-Core](https://img.shields.io/badge/Install_HVE--Core-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](#automated-installation)
+
+**Quick Install:** One-click installation via the `hve-core-installer` agent in VS Code (~30 seconds)
+
 ## Overview
 
 HVE Core provides a unified set of optimized GitHub Copilot and Microsoft 365 Copilot chat modes, along with curated instructions and prompt templates, to deliver intelligent, context-aware interactions for building solutions on Azure. Whether you're tackling greenfield projects or modernizing existing systems, HVE Core reduces time-to-value and simplifies complex engineering tasks.
 
 ## Quick Start
 
+### Automated Installation
+
+**Recommended:** Use the `hve-core-installer` agent for automated setup:
+
+1. Open GitHub Copilot Chat in VS Code (Ctrl+Alt+I)
+2. Select the `hve-core-installer` agent from the agent picker dropdown
+3. Follow the guided installation (~30 seconds)
+
+The installer will:
+
+* Clone the hve-core repository as a sibling to your workspace
+* Validate the repository structure
+* Update your VS Code settings.json with chat mode, prompt, and instruction paths
+* Make all HVE Core components immediately available
+
+### Manual Installation
+
+To use HVE Core's GitHub Copilot customizations in your project, clone this repository as a sibling to your project and configure a multi-root workspace. See the [Getting Started Guide](docs/getting-started.md) for step-by-step instructions.
+
 ### Prerequisites
 
 * GitHub Copilot subscription
 * VS Code with GitHub Copilot extension
+* Git installed and available in PATH
 * Node.js and npm (for development and validation)
 
-### Setup
-
-To use HVE Core's GitHub Copilot customizations in your project, clone this repository as a sibling to your project and configure a multi-root workspace. See the [Getting Started Guide](docs/getting-started.md) for step-by-step instructions.
-
 ### Using Chat Modes
 
 Select specialized AI assistants from the agent picker dropdown in GitHub Copilot Chat:
diff --git a/docs/getting-started.md b/docs/getting-started.md
index c8839ef..c1bc702 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -2,7 +2,7 @@
 title: Getting Started with HVE Core
 description: Quick setup guide for using HVE Core Copilot customizations in your projects
 author: Microsoft
-ms.date: 2025-11-15
+ms.date: 2025-11-21
 ms.topic: tutorial
 keywords:
   - github copilot
@@ -14,7 +14,24 @@ estimated_reading_time: 5
 
 This guide shows you how to configure your project to use HVE Core's GitHub Copilot customizations (chat modes, instructions, and prompts).
 
-## Prerequisites
+## Automated Installation (Recommended)
+
+**Fastest method:** Use the `hve-core-installer` agent for automated setup (~30 seconds):
+
+1. Open GitHub Copilot Chat in VS Code (Ctrl+Alt+I)
+2. Select the `hve-core-installer` agent from the agent picker dropdown
+3. Follow the guided installation
+
+The installer will:
+
+* Clone the hve-core repository as a sibling to your workspace
+* Validate the repository structure
+* Update your VS Code settings.json with chat mode, prompt, and instruction paths
+* Make all HVE Core components immediately available
+
+## Manual Installation
+
+### Prerequisites
 
 * VS Code with GitHub Copilot extension installed
 * Both repositories cloned as siblings on your machine
@@ -95,6 +112,43 @@ Check that everything works:
 
 ## Troubleshooting
 
+### Installation Issues
+
+If the automated installation encounters issues, try these solutions:
+
+#### "Not in a git repository" error
+
+* Ensure you have a git repository initialized in your current workspace
+* Run `git init` if needed, then retry installation
+
+#### "Git not found" error
+
+* Install Git and ensure it's available in your PATH
+* Verify: Open terminal and run `git --version`
+* Windows: Download from [git-scm.com](https://git-scm.com)
+* macOS: Install via Homebrew `brew install git` or Xcode Command Line Tools
+* Linux: Install via package manager `apt install git` or `yum install git`
+
+#### "Clone failed" error
+
+* Check network connectivity to github.com
+* Verify you don't already have a `../hve-core` directory
+* Try cloning manually: `git clone https://github.com/microsoft/hve-core.git ../hve-core`
+
+#### "Settings update failed" error
+
+* Check VS Code settings.json file permissions
+* Manually backup your settings: Copy `settings.json` before retrying
+* Verify settings.json is valid JSON (no syntax errors)
+
+#### Agent not available
+
+* Ensure GitHub Copilot extension is installed and active
+* Reload VS Code window: Ctrl+Shift+P → "Developer: Reload Window"
+* Check that hve-core repository is cloned as a sibling to your workspace
+
+### Configuration Issues
+
 **Problem:** Copilot not discovering hve-core customizations
 
 **Solution:** Ensure you opened the `.code-workspace` file, not just the folder. The window title should show the workspace name, and both folders should appear in Explorer.

From 2e0a45ca949ade00e17d324e474d08d6c6ddb93d Mon Sep 17 00:00:00 2001
From: Bill Berry <wberry@microsoft.com>
Date: Fri, 21 Nov 2025 19:06:41 -0800
Subject: [PATCH 2/5] fix: resolve all PR82 code review comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- fix agent schema and add to schema mapping
- fix prompt, instruction, and chatmode schemas
- correct agent file tool names and bash commands
- fix documentation badge and marketing text

✅ - Generated by Copilot
---
 .github/agents/hve-core-installer.agent.md    | 20 +++--
 README.md                                     |  4 +-
 .../schemas/agent-frontmatter.schema.json     | 73 +++++++++++++++++++
 .../schemas/chatmode-frontmatter.schema.json  | 17 +++--
 .../instruction-frontmatter.schema.json       | 25 ++-----
 .../schemas/prompt-frontmatter.schema.json    | 34 +++++----
 scripts/linting/schemas/schema-mapping.json   |  6 ++
 7 files changed, 128 insertions(+), 51 deletions(-)
 create mode 100644 scripts/linting/schemas/agent-frontmatter.schema.json

diff --git a/.github/agents/hve-core-installer.agent.md b/.github/agents/hve-core-installer.agent.md
index 448e880..73f084c 100644
--- a/.github/agents/hve-core-installer.agent.md
+++ b/.github/agents/hve-core-installer.agent.md
@@ -1,6 +1,6 @@
 ---
 description: 'Automated installer for HVE-Core chatmodes, prompts, and instructions - Brought to you by microsoft/hve-core'
-tools: ['runCommands', 'edit/createFile', 'edit/editFiles', 'search']
+tools: ['runCommand', 'edit/createFile', 'edit/editFiles', 'search']
 ---
 # HVE-Core Installer Agent
 
@@ -51,7 +51,7 @@ You MUST:
 
 ### Step 2: Detect Workspace Root
 
-You MUST detect the current workspace root using `runCommands`.
+You MUST detect the current workspace root using `runCommand`.
 
 **PowerShell:**
 
@@ -101,9 +101,7 @@ hve_core_target="$workspace_parent/hve-core"
 if [ -d "$hve_core_target" ]; then
     echo "✅ hve-core already exists at: $hve_core_target"
 else
-    cd "$workspace_parent"
-    git clone https://github.com/microsoft/hve-core.git
-    cd - > /dev/null
+    (cd "$workspace_parent" && git clone https://github.com/microsoft/hve-core.git)
     echo "✅ Cloned hve-core to: $hve_core_target"
 fi
 ```
@@ -116,7 +114,7 @@ You MUST handle clone failures by:
 
 ### Step 4: Validate Repository Structure
 
-You MUST validate that required directories exist using `runCommands`.
+You MUST validate that required directories exist using `runCommand`.
 
 **PowerShell:**
 
@@ -170,7 +168,7 @@ I will now update your VS Code settings.json to add hve-core paths.
 
 Changes to be made:
 • Add "../hve-core/.github/chatmodes" to chat.modeFilesLocations
-• Add "../hve-core/.github/prompts" to chat.promptFilesLocations  
+• Add "../hve-core/.github/prompts" to chat.promptFilesLocations
 • Add "../hve-core/.github/instructions" to chat.instructionsFilesLocations
 
 A timestamped backup will be created before any modifications.
@@ -180,9 +178,9 @@ A timestamped backup will be created before any modifications.
 
 If user declines, you MUST respond: "Installation cancelled. No changes were made to your settings."
 
-Upon authorization, you MUST use `edit/editFiles` tool to:
+Upon authorization, you MUST:
 
-1. Determine settings.json path based on OS.
+1. Determine settings.json path based on OS using `runCommand`:
 
 **PowerShell (cross-platform):**
 
@@ -208,9 +206,9 @@ else
 fi
 ```
 
-1. Read current settings.json content
+2. Read current settings.json content using appropriate tools
 
-2. Parse JSON and add paths to arrays (avoid duplicates):
+3. Parse JSON and add paths to arrays (avoid duplicates), then use `edit/editFiles` to write updated JSON:
    * If `chat.modeFilesLocations` doesn't exist, create it as empty array
    * If `chat.promptFilesLocations` doesn't exist, create it as empty array
    * If `chat.instructionsFilesLocations` doesn't exist, create it as empty array
diff --git a/README.md b/README.md
index 20297fb..6e12b37 100644
--- a/README.md
+++ b/README.md
@@ -17,9 +17,9 @@ estimated_reading_time: 3
 
 An open-source library of Hypervelocity Engineering components that accelerates Azure solution development by enabling advanced conversational workflows.
 
-[![Install HVE-Core](https://img.shields.io/badge/Install_HVE--Core-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](#automated-installation)
+[![Install HVE Core](https://img.shields.io/badge/Install_HVE_Core-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](#automated-installation)
 
-**Quick Install:** One-click installation via the `hve-core-installer` agent in VS Code (~30 seconds)
+**Quick Install:** Automated installation via the `hve-core-installer` agent in VS Code (~30 seconds)
 
 ## Overview
 
diff --git a/scripts/linting/schemas/agent-frontmatter.schema.json b/scripts/linting/schemas/agent-frontmatter.schema.json
new file mode 100644
index 0000000..337c7f1
--- /dev/null
+++ b/scripts/linting/schemas/agent-frontmatter.schema.json
@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/microsoft/hve-core/schemas/agent-frontmatter.schema.json",
+  "title": "Agent File Frontmatter Schema",
+  "description": "Frontmatter schema for .agent.md files in VS Code custom agents",
+  "type": "object",
+  "required": ["description"],
+  "properties": {
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A brief description of the custom agent, shown as placeholder text in the chat input field"
+    },
+    "name": {
+      "type": "string",
+      "description": "The name of the custom agent. If not specified, the file name is used"
+    },
+    "argument-hint": {
+      "type": "string",
+      "description": "Optional hint text shown in the chat input field to guide users on how to interact with the custom agent"
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "A list of tool or tool set names that are available for this custom agent. Can include built-in tools, tool sets, MCP tools, or tools contributed by extensions"
+    },
+    "model": {
+      "type": "string",
+      "description": "The AI model to use when running the prompt. If not specified, the currently selected model in model picker is used"
+    },
+    "target": {
+      "type": "string",
+      "enum": ["vscode", "github-copilot"],
+      "description": "The target environment or context for the custom agent"
+    },
+    "mcp-servers": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      },
+      "description": "Optional list of Model Context Protocol (MCP) server config json to use with custom agents in GitHub Copilot"
+    },
+    "handoffs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["label", "agent", "prompt"],
+        "properties": {
+          "label": {
+            "type": "string",
+            "description": "The display text shown on the handoff button"
+          },
+          "agent": {
+            "type": "string",
+            "description": "The target agent identifier to switch to"
+          },
+          "prompt": {
+            "type": "string",
+            "description": "The prompt text to send to the target agent"
+          },
+          "send": {
+            "type": "boolean",
+            "description": "Optional boolean flag to auto-submit the prompt (default is false)"
+          }
+        }
+      },
+      "description": "Optional list of suggested next actions or prompts to transition between custom agents. Handoff buttons appear as interactive suggestions after a chat response completes"
+    }
+  },
+  "additionalProperties": true
+}
diff --git a/scripts/linting/schemas/chatmode-frontmatter.schema.json b/scripts/linting/schemas/chatmode-frontmatter.schema.json
index 3c92a4d..e2c9b3f 100644
--- a/scripts/linting/schemas/chatmode-frontmatter.schema.json
+++ b/scripts/linting/schemas/chatmode-frontmatter.schema.json
@@ -2,34 +2,39 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/microsoft/hve-core/schemas/chatmode-frontmatter.schema.json",
   "title": "ChatMode File Frontmatter Schema",
-  "description": "Frontmatter schema for .chatmode.md files",
+  "description": "Frontmatter schema for .chatmode.md files (legacy/deprecated format)",
   "type": "object",
   "required": ["description"],
   "properties": {
     "description": {
       "type": "string",
       "minLength": 1,
-      "description": "Brief description of the chat mode functionality"
+      "description": "Concise explanation of chatmode functionality (10-200 characters)"
     },
     "tools": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Array of tools available in this chat mode"
+      "description": "List of GitHub Copilot tools available to this agent (e.g., codebase, search, editFiles, runCommands)"
     },
     "mode": {
       "type": "string",
       "enum": ["agent", "assistant", "copilot"],
-      "description": "Chat mode type"
+      "description": "Defines agent interaction pattern"
+    },
+    "model": {
+      "type": "string",
+      "description": "The language model to use (e.g., 'Claude Sonnet 4')"
     },
     "version": {
       "type": "string",
-      "description": "Version of the chat mode configuration"
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version number (e.g., '1.0.0')"
     },
     "author": {
       "type": "string",
-      "description": "Author or team responsible for the chat mode"
+      "description": "Attribution for chatmode creator (e.g., 'microsoft/hve-core')"
     }
   },
   "additionalProperties": true
diff --git a/scripts/linting/schemas/instruction-frontmatter.schema.json b/scripts/linting/schemas/instruction-frontmatter.schema.json
index f101d72..81850d9 100644
--- a/scripts/linting/schemas/instruction-frontmatter.schema.json
+++ b/scripts/linting/schemas/instruction-frontmatter.schema.json
@@ -2,32 +2,23 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/microsoft/hve-core/schemas/instruction-frontmatter.schema.json",
   "title": "Instruction File Frontmatter Schema",
-  "description": "Frontmatter schema for .instructions.md files in .github directory",
+  "description": "Frontmatter schema for .instructions.md files per VS Code Copilot specification",
   "type": "object",
-  "required": ["description"],
   "properties": {
     "description": {
       "type": "string",
       "minLength": 1,
-      "description": "Brief description of the instruction file purpose"
+      "description": "A short description of the instructions file"
     },
-    "applyTo": {
-      "type": "string",
-      "pattern": "^(\\*\\*/)?[*\\w.-]+(/[*\\w.-]+)*(/\\*{1,2})?(\\.\\w+)?(,\\s*(\\*\\*/)?[*\\w.-]+(/[*\\w.-]+)*(/\\*{1,2})?(\\.\\w+)?)*$",
-      "description": "Glob patterns for file matching, supports comma-separated values like '**/*.py, **/*.ipynb' and directory patterns like '**/.copilot-tracking/pr/new/**'"
-    },
-    "author": {
+    "name": {
       "type": "string",
-      "description": "Author or team responsible for the instructions"
+      "minLength": 1,
+      "description": "The name of the instructions file, used in the UI. If not specified, the file name is used."
     },
-    "version": {
+    "applyTo": {
       "type": "string",
-      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
-      "description": "Version number for the instruction set"
-    },
-    "lastUpdated": {
-      "$ref": "base-frontmatter.schema.json#/definitions/iso8601Date"
+      "description": "Optional glob pattern that defines which files the instructions should be applied to automatically, relative to the workspace root. Use ** to apply to all files. If not specified, instructions are not applied automatically."
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }
\ No newline at end of file
diff --git a/scripts/linting/schemas/prompt-frontmatter.schema.json b/scripts/linting/schemas/prompt-frontmatter.schema.json
index 72a4058..0a3c81c 100644
--- a/scripts/linting/schemas/prompt-frontmatter.schema.json
+++ b/scripts/linting/schemas/prompt-frontmatter.schema.json
@@ -2,35 +2,39 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/microsoft/hve-core/schemas/prompt-frontmatter.schema.json",
   "title": "Prompt File Frontmatter Schema",
-  "description": "Frontmatter schema for .prompt.md files",
+  "description": "Frontmatter schema for .prompt.md files per VS Code Copilot specification",
   "type": "object",
+  "required": ["description"],
   "properties": {
     "description": {
       "type": "string",
       "minLength": 1,
-      "description": "Brief description of the prompt purpose"
+      "description": "A short description of the prompt"
     },
-    "mode": {
+    "name": {
       "type": "string",
-      "enum": ["agent", "assistant", "copilot", "workflow"],
-      "description": "Prompt mode or context"
+      "minLength": 1,
+      "description": "The name of the prompt, used after typing / in chat. Defaults to filename if not specified."
     },
-    "category": {
+    "argument-hint": {
       "type": "string",
-      "enum": ["ado", "git", "documentation", "workflow", "development"],
-      "description": "Prompt category for organization"
+      "description": "Optional hint text shown in the chat input to guide users on expected arguments"
     },
-    "version": {
+    "agent": {
       "type": "string",
-      "description": "Version of the prompt"
+      "description": "The agent used for running the prompt. Options: ask, edit, agent (default), or a custom agent name"
     },
-    "author": {
+    "model": {
       "type": "string",
-      "description": "Author or team responsible for the prompt"
+      "description": "The language model to use when running the prompt. Defaults to current selection if not specified."
     },
-    "lastUpdated": {
-      "$ref": "base-frontmatter.schema.json#/definitions/iso8601Date"
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of tool names or tool set names available for this prompt. Can include built-in tools, MCP tools (<server>/*), or extension tools."
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }
\ No newline at end of file
diff --git a/scripts/linting/schemas/schema-mapping.json b/scripts/linting/schemas/schema-mapping.json
index 02d6480..2a1264e 100644
--- a/scripts/linting/schemas/schema-mapping.json
+++ b/scripts/linting/schemas/schema-mapping.json
@@ -31,6 +31,12 @@
       "scope": "github-prompts",
       "schema": "prompt-frontmatter.schema.json",
       "description": "Prompt files in .github directory"
+    },
+    {
+      "pattern": ".github/**/*.agent.md",
+      "scope": "github-agents",
+      "schema": "agent-frontmatter.schema.json",
+      "description": "Agent files in .github directory"
     }
   ],
   "defaultSchema": "base-frontmatter.schema.json"

From 75d57d4577bce603b0fed793ec148c8f51019cc2 Mon Sep 17 00:00:00 2001
From: Bill Berry <wberry@microsoft.com>
Date: Fri, 21 Nov 2025 19:18:36 -0800
Subject: [PATCH 3/5] fix(agents): correct ordered list indentation for
 markdownlint MD029
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🔧 - Generated by Copilot
---
 .github/agents/hve-core-installer.agent.md | 59 +++++++++++-----------
 1 file changed, 30 insertions(+), 29 deletions(-)

diff --git a/.github/agents/hve-core-installer.agent.md b/.github/agents/hve-core-installer.agent.md
index 73f084c..fe448a6 100644
--- a/.github/agents/hve-core-installer.agent.md
+++ b/.github/agents/hve-core-installer.agent.md
@@ -182,41 +182,42 @@ Upon authorization, you MUST:
 
 1. Determine settings.json path based on OS using `runCommand`:
 
-**PowerShell (cross-platform):**
-
-```powershell
-if ($IsWindows -or $env:OS -eq "Windows_NT") {
-    $settingsPath = Join-Path $env:APPDATA "Code\User\settings.json"
-} elseif ($IsMacOS -or $env:OS -eq "Darwin") {
-    $settingsPath = Join-Path $env:HOME "Library/Application Support/Code/User/settings.json"
-} else {
-    $settingsPath = Join-Path $env:HOME ".config/Code/User/settings.json"
-}
-```
+    **PowerShell (cross-platform):**
+
+    ```powershell
+    if ($IsWindows -or $env:OS -eq "Windows_NT") {
+        $settingsPath = Join-Path $env:APPDATA "Code\User\settings.json"
+    } elseif ($IsMacOS -or $env:OS -eq "Darwin") {
+        $settingsPath = Join-Path $env:HOME "Library/Application Support/Code/User/settings.json"
+    } else {
+        $settingsPath = Join-Path $env:HOME ".config/Code/User/settings.json"
+    }
+    ```
 
-**Bash:**
+    **Bash:**
 
-```bash
-if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
-    settings_path="$APPDATA/Code/User/settings.json"
-elif [[ "$OSTYPE" == "darwin"* ]]; then
-    settings_path="$HOME/Library/Application Support/Code/User/settings.json"
-else
-    settings_path="$HOME/.config/Code/User/settings.json"
-fi
-```
+    ```bash
+    if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+        settings_path="$APPDATA/Code/User/settings.json"
+    elif [[ "$OSTYPE" == "darwin"* ]]; then
+        settings_path="$HOME/Library/Application Support/Code/User/settings.json"
+    else
+        settings_path="$HOME/.config/Code/User/settings.json"
+    fi
+    ```
 
 2. Read current settings.json content using appropriate tools
 
 3. Parse JSON and add paths to arrays (avoid duplicates), then use `edit/editFiles` to write updated JSON:
-   * If `chat.modeFilesLocations` doesn't exist, create it as empty array
-   * If `chat.promptFilesLocations` doesn't exist, create it as empty array
-   * If `chat.instructionsFilesLocations` doesn't exist, create it as empty array
-   * Add `../hve-core/.github/chatmodes` if not already present
-   * Add `../hve-core/.github/prompts` if not already present
-   * Add `../hve-core/.github/instructions` if not already present
-
-3. Write updated JSON back to settings.json
+
+    * If `chat.modeFilesLocations` doesn't exist, create it as empty array
+    * If `chat.promptFilesLocations` doesn't exist, create it as empty array
+    * If `chat.instructionsFilesLocations` doesn't exist, create it as empty array
+    * Add `../hve-core/.github/chatmodes` if not already present
+    * Add `../hve-core/.github/prompts` if not already present
+    * Add `../hve-core/.github/instructions` if not already present
+
+4. Write updated JSON back to settings.json
 
 You MUST report each change:
 

From ec9e0d5b88a6f7f342104053f800401c7e662816 Mon Sep 17 00:00:00 2001
From: Bill Berry <wberry@microsoft.com>
Date: Wed, 26 Nov 2025 12:39:14 -0800
Subject: [PATCH 4/5] fix(agent): address PR #82 review comments for
 hve-core-installer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- add .github/agents to PowerShell and Bash requiredPaths validation
- fix PowerShell OS detection to use reliable automatic variables
- add Windows PowerShell 5.1 fallback for missing $IsWindows
- fix Bash Windows path handling with cygpath conversion
- add cygwin OSTYPE detection for broader Git Bash support

🔧 - Generated by Copilot
---
 .github/agents/hve-core-installer.agent.md    | 22 +++++++++++++------
 .github/instructions/markdown.instructions.md |  7 +++---
 2 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/.github/agents/hve-core-installer.agent.md b/.github/agents/hve-core-installer.agent.md
index fe448a6..59ee731 100644
--- a/.github/agents/hve-core-installer.agent.md
+++ b/.github/agents/hve-core-installer.agent.md
@@ -120,7 +120,7 @@ You MUST validate that required directories exist using `runCommand`.
 
 ```powershell
 $hveCoreTarget = Join-Path (Split-Path (git rev-parse --show-toplevel) -Parent) "hve-core"
-$requiredPaths = @(".github/chatmodes", ".github/prompts", ".github/instructions")
+$requiredPaths = @(".github/chatmodes", ".github/prompts", ".github/instructions", ".github/agents")
 $valid = $true
 foreach ($path in $requiredPaths) {
     if (-not (Test-Path (Join-Path $hveCoreTarget $path))) {
@@ -136,7 +136,7 @@ if ($valid) { Write-Host "✅ Repository structure validated" }
 ```bash
 workspace_root=$(git rev-parse --show-toplevel)
 hve_core_target="$(dirname "$workspace_root")/hve-core"
-required_paths=(".github/chatmodes" ".github/prompts" ".github/instructions")
+required_paths=(".github/chatmodes" ".github/prompts" ".github/instructions" ".github/agents")
 valid=true
 
 for path in "${required_paths[@]}"; do
@@ -185,20 +185,28 @@ Upon authorization, you MUST:
     **PowerShell (cross-platform):**
 
     ```powershell
-    if ($IsWindows -or $env:OS -eq "Windows_NT") {
+    if ($IsWindows) {
         $settingsPath = Join-Path $env:APPDATA "Code\User\settings.json"
-    } elseif ($IsMacOS -or $env:OS -eq "Darwin") {
+    } elseif ($IsMacOS) {
         $settingsPath = Join-Path $env:HOME "Library/Application Support/Code/User/settings.json"
-    } else {
+    } elseif ($IsLinux) {
         $settingsPath = Join-Path $env:HOME ".config/Code/User/settings.json"
+    } else {
+        # Fallback for Windows PowerShell 5.1 (lacks $IsWindows)
+        $settingsPath = Join-Path $env:APPDATA "Code\User\settings.json"
     }
     ```
 
     **Bash:**
 
     ```bash
-    if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
-        settings_path="$APPDATA/Code/User/settings.json"
+    if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" || "$OSTYPE" == "win32" ]]; then
+        # Convert Windows path to Unix-style for Git Bash/MSYS
+        if command -v cygpath &> /dev/null; then
+            settings_path="$(cygpath "$APPDATA")/Code/User/settings.json"
+        else
+            settings_path="${APPDATA//\\//}/Code/User/settings.json"
+        fi
     elif [[ "$OSTYPE" == "darwin"* ]]; then
         settings_path="$HOME/Library/Application Support/Code/User/settings.json"
     else
diff --git a/.github/instructions/markdown.instructions.md b/.github/instructions/markdown.instructions.md
index 12fad5c..19fe655 100644
--- a/.github/instructions/markdown.instructions.md
+++ b/.github/instructions/markdown.instructions.md
@@ -27,7 +27,7 @@ These instructions define the Markdown style guide enforced by markdownlint in t
 * Surround each heading with a blank line above and below (except at file start/end).
 * Do not end headings with punctuation such as `. , ; : !` or their full-width variants.
 * Avoid duplicate headings under the same parent section; make them unique.
-* Begin the file with a top-level heading after YAML frontmatter (if present). BOTH frontmatter `title:` field AND H1 heading are required when frontmatter is used. Do not include preamble text before the title.
+* Do NOT use an H1 heading when YAML frontmatter contains a `title:` field. The frontmatter title satisfies MD025 and MD041. Start content with H2 or below after frontmatter. If no frontmatter exists, begin the file with a top-level heading.
 * Use exactly one space after the `#` characters in headings; do not omit or use multiple spaces.
 * If you close ATX headings with trailing `#` characters, use a single space between the text and both the opening and closing hashes; do not use multiple spaces on either side.
 * Use only one top-level heading per document; subsequent sections must use lower levels.
@@ -48,9 +48,8 @@ These instructions define the Markdown style guide enforced by markdownlint in t
 * Frontmatter MUST be the first content in the file (before H1 heading)
 * Use triple-dash delimiters (---) on separate lines to wrap frontmatter YAML
 * Frontmatter provides machine-readable metadata for validation, SEO, and site generation
-* BOTH frontmatter `title:` field AND H1 heading are required (not either/or)
-  * Frontmatter title: Metadata for search indexing, HTML `<title>` tag, navigation
-  * H1 heading: Content title for semantic HTML structure and accessibility
+* Do NOT use an H1 heading when frontmatter includes a `title:` field; the title in frontmatter acts as the document title per MD025/MD041
+* Start document content with H2 or below when frontmatter is present
 
 ### Required Fields by File Type
 

From 002bab9adb9b60e04d274e85c359efdc5ba3cf2c Mon Sep 17 00:00:00 2001
From: Bill Berry <wberry@microsoft.com>
Date: Wed, 26 Nov 2025 13:06:58 -0800
Subject: [PATCH 5/5] fix(agent): address additional PR #82 Copilot review
 comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- reorder Step 5 to detect OS path before creating backup
- add timestamped backup instructions for settings.json
- fix PowerShell OS detection using [System.Environment]::OSVersion.Platform
- remove .github/agents from validation (no VS Code setting required)
- fix agent schema: additionalProperties false for consistency

🔧 - Generated by Copilot
---
 .github/agents/hve-core-installer.agent.md    | 48 +++++++++++++++----
 .../schemas/agent-frontmatter.schema.json     |  2 +-
 .../instruction-frontmatter.schema.json       |  1 +
 3 files changed, 41 insertions(+), 10 deletions(-)

diff --git a/.github/agents/hve-core-installer.agent.md b/.github/agents/hve-core-installer.agent.md
index 59ee731..05e4cdc 100644
--- a/.github/agents/hve-core-installer.agent.md
+++ b/.github/agents/hve-core-installer.agent.md
@@ -120,7 +120,7 @@ You MUST validate that required directories exist using `runCommand`.
 
 ```powershell
 $hveCoreTarget = Join-Path (Split-Path (git rev-parse --show-toplevel) -Parent) "hve-core"
-$requiredPaths = @(".github/chatmodes", ".github/prompts", ".github/instructions", ".github/agents")
+$requiredPaths = @(".github/chatmodes", ".github/prompts", ".github/instructions")
 $valid = $true
 foreach ($path in $requiredPaths) {
     if (-not (Test-Path (Join-Path $hveCoreTarget $path))) {
@@ -136,7 +136,7 @@ if ($valid) { Write-Host "✅ Repository structure validated" }
 ```bash
 workspace_root=$(git rev-parse --show-toplevel)
 hve_core_target="$(dirname "$workspace_root")/hve-core"
-required_paths=(".github/chatmodes" ".github/prompts" ".github/instructions" ".github/agents")
+required_paths=(".github/chatmodes" ".github/prompts" ".github/instructions")
 valid=true
 
 for path in "${required_paths[@]}"; do
@@ -185,14 +185,16 @@ Upon authorization, you MUST:
     **PowerShell (cross-platform):**
 
     ```powershell
-    if ($IsWindows) {
+    # Cross-version OS detection (PowerShell Core and Windows PowerShell 5.1)
+    $platform = [System.Environment]::OSVersion.Platform
+    if ($platform -eq "Win32NT") {
         $settingsPath = Join-Path $env:APPDATA "Code\User\settings.json"
-    } elseif ($IsMacOS) {
+    } elseif ($platform -eq "Unix" -and $IsMacOS) {
         $settingsPath = Join-Path $env:HOME "Library/Application Support/Code/User/settings.json"
-    } elseif ($IsLinux) {
+    } elseif ($platform -eq "Unix") {
         $settingsPath = Join-Path $env:HOME ".config/Code/User/settings.json"
     } else {
-        # Fallback for Windows PowerShell 5.1 (lacks $IsWindows)
+        # Fallback: Assume Windows
         $settingsPath = Join-Path $env:APPDATA "Code\User\settings.json"
     }
     ```
@@ -214,9 +216,37 @@ Upon authorization, you MUST:
     fi
     ```
 
-2. Read current settings.json content using appropriate tools
+2. Create a timestamped backup of settings.json using `runCommand`:
 
-3. Parse JSON and add paths to arrays (avoid duplicates), then use `edit/editFiles` to write updated JSON:
+    **PowerShell:**
+
+    ```powershell
+    $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
+    $backupPath = "$settingsPath.backup.$timestamp"
+    Copy-Item -Path $settingsPath -Destination $backupPath -ErrorAction SilentlyContinue
+    if (Test-Path $backupPath) {
+        Write-Host "✅ Backup created: $backupPath"
+    } else {
+        Write-Host "⚠️ No existing settings.json to backup (new installation)"
+    }
+    ```
+
+    **Bash:**
+
+    ```bash
+    timestamp=$(date +"%Y%m%d-%H%M%S")
+    backup_path="${settings_path}.backup.${timestamp}"
+    if [ -f "$settings_path" ]; then
+        cp "$settings_path" "$backup_path"
+        echo "✅ Backup created: $backup_path"
+    else
+        echo "⚠️ No existing settings.json to backup (new installation)"
+    fi
+    ```
+
+3. Read current settings.json content using appropriate tools
+
+4. Parse JSON and add paths to arrays (avoid duplicates), then use `edit/editFiles` to write updated JSON:
 
     * If `chat.modeFilesLocations` doesn't exist, create it as empty array
     * If `chat.promptFilesLocations` doesn't exist, create it as empty array
@@ -225,7 +255,7 @@ Upon authorization, you MUST:
     * Add `../hve-core/.github/prompts` if not already present
     * Add `../hve-core/.github/instructions` if not already present
 
-4. Write updated JSON back to settings.json
+5. Write updated JSON back to settings.json
 
 You MUST report each change:
 
diff --git a/scripts/linting/schemas/agent-frontmatter.schema.json b/scripts/linting/schemas/agent-frontmatter.schema.json
index 337c7f1..669b103 100644
--- a/scripts/linting/schemas/agent-frontmatter.schema.json
+++ b/scripts/linting/schemas/agent-frontmatter.schema.json
@@ -69,5 +69,5 @@
       "description": "Optional list of suggested next actions or prompts to transition between custom agents. Handoff buttons appear as interactive suggestions after a chat response completes"
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }
diff --git a/scripts/linting/schemas/instruction-frontmatter.schema.json b/scripts/linting/schemas/instruction-frontmatter.schema.json
index 81850d9..a5986b9 100644
--- a/scripts/linting/schemas/instruction-frontmatter.schema.json
+++ b/scripts/linting/schemas/instruction-frontmatter.schema.json
@@ -4,6 +4,7 @@
   "title": "Instruction File Frontmatter Schema",
   "description": "Frontmatter schema for .instructions.md files per VS Code Copilot specification",
   "type": "object",
+  "required": ["description"],
   "properties": {
     "description": {
       "type": "string",