feat(agent): Add automated installation via hve-core-installer agent

.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
 

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:** Automated 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:

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.

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": false
+}

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

scripts/linting/schemas/instruction-frontmatter.schema.json

@@ -2,32 +2,24 @@
   "$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
 }

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
 }

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"