diff --git a/README.md b/README.md index bc0301f0a..9bf05cd11 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ --- title: HVE Core -description: Hypervelocity Engineering prompt library for GitHub Copilot with constraint-based AI workflows and validated artifacts +description: Hypervelocity Engineering prompt library for GitHub Copilot with convention-driven AI workflows and validated artifacts author: Microsoft -ms.date: 2026-03-22 +ms.date: 2026-05-04 ms.topic: overview keywords: - hypervelocity engineering @@ -24,7 +24,7 @@ estimated_reading_time: 3 [![Documentation](https://img.shields.io/badge/docs-microsoft.github.io%2Fhve--core-blue)](https://microsoft.github.io/hve-core/) -Hypervelocity Engineering (HVE) Core gives you specialized agents, auto-applied coding instructions, reusable prompts, and validated skills for GitHub Copilot. Turn Copilot into a constraint-based engineering workflow that scales from solo developers to enterprise teams. +Hypervelocity Engineering (HVE) Core (accelerating software delivery through AI-augmented workflows) gives you specialized agents, auto-applied coding instructions, reusable prompts, and validated skills for GitHub Copilot. Turn Copilot into a convention-driven engineering workflow (agents follow your repository's standards automatically) that scales from solo developers to enterprise teams. > [!TIP] > Install from the VS Code Marketplace in under 30 seconds. See the [Installation Guide](docs/getting-started/install.md) for all options. @@ -32,17 +32,31 @@ Hypervelocity Engineering (HVE) Core gives you specialized agents, auto-applied ## Quick Start 1. Install the [HVE Core extension](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) from the VS Code Marketplace. -2. Open any project and launch GitHub Copilot Chat (`Ctrl+Alt+I`). -3. Select an agent from the picker (try **rpi-agent**, **task-researcher**, or **memory**) and start a conversation. + + [![Install HVE Core - Flagship Collection](https://img.shields.io/badge/VS%20Code-Install%20HVE%20Core-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) [![Install HVE Core - All Collection](https://img.shields.io/badge/VS%20Code-Install%20All%20Collections-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core-all) + +1. Open any project and launch GitHub Copilot Chat (`Ctrl+Alt+I`). +2. Select an agent from the picker (try **rpi-agent**, **task-researcher**, or **memory**) and start a conversation. That's it. Agents, instructions, and prompts activate automatically once the extension is installed. +**Using GitHub Copilot CLI?** Install as a plugin instead: + +```bash +copilot plugin marketplace add microsoft/hve-core +copilot plugin install hve-core-all@hve-core +``` + +See [CLI Plugins](docs/getting-started/methods/cli-plugins.md) for usage details. + Ready for more? Follow the [Getting Started Guide](docs/getting-started/README.md). ## Choose Your Extension Two VS Code extensions serve different needs: +Collections are curated bundles of agents, prompts, instructions, and skills targeting specific workflows or domains. The **HVE Core** extension installs the flagship collection (41 artifacts for RPI (Research → Plan → Implement) workflows). Install **HVE Core All** for the complete bundle (221 artifacts across all domains). + | Extension | What it includes | Best for | |-------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|-------------------------------------------------------------------------| | [HVE Core All](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core-all) | Every collection: all agents, prompts, instructions, and skills | Individual developers and teams that want the full library | @@ -50,6 +64,8 @@ Two VS Code extensions serve different needs: Not sure which to choose? Start with HVE Core All. You can switch to HVE Installer later if you need finer control over which collections are active. See the [Collections Overview](docs/getting-started/collections.md) for a comparison of all available bundles. +**Copilot CLI users:** All collections are also available as [CLI plugins](docs/getting-started/methods/cli-plugins.md) via `copilot plugin install @hve-core`. + ## What's Included | Component | Count | Description | Documentation | @@ -60,6 +76,14 @@ Not sure which to choose? Start with HVE Core All. You can switch to HVE Install | Skills | 11 | Self-contained packages with cross-platform scripts and guidance | [Skills](.github/skills/) | | Scripts | N/A | Validation tools for linting, security, and quality | [Scripts](scripts/README.md) | +> [!TIP] +> **Component types at a glance:** +> +> * Agents - Specialized AI personas with domain expertise (e.g., Task Researcher, Security Planner) +> * Prompts - Predefined commands that trigger specific workflows (e.g., `/task-research`, `/git-commit`) +> * Instructions - Coding standards and conventions auto-applied to matching files +> * Skills - Reusable tool packages that extend agent capabilities + ## Documentation Full documentation is available at ****. diff --git a/docs/getting-started/collections.md b/docs/getting-started/collections.md index ec32ea6d1..46d53be83 100644 --- a/docs/getting-started/collections.md +++ b/docs/getting-started/collections.md @@ -95,6 +95,19 @@ If you prefer a leaner workspace or need to standardize which artifacts are avai > [!TIP] > You can always switch later. Start with `hve-core-all` to explore, then move to the installer approach when you know which collections your team needs. +## After Installing a Collection + +Once a collection is installed, its artifacts activate automatically: + +1. **Agents** appear in the Copilot Chat agent picker (press `Ctrl+.` or use the dropdown). +2. **Prompts** are available as slash commands (type `/` in Copilot Chat to see them). +3. **Instructions** apply automatically to matching files based on their `applyTo` patterns. +4. **Skills** extend agent capabilities without additional configuration. + +To verify installation, open Copilot Chat and check that collection-specific agents appear in the agent picker. For example, installing the `hve-core` collection adds Task Researcher, Task Planner, Task Implementor, and Memory agents. + +To add more collections later, search "HVE" in the VS Code Extensions marketplace or use the selective install commands from the table above. + --- diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md index 433f001e5..c90892803 100644 --- a/docs/getting-started/install.md +++ b/docs/getting-started/install.md @@ -63,6 +63,35 @@ Teams that only need specific domains can use the **HVE Installer** extension to ⭐ **VS Code Extension** is the recommended method for most users who don't need customization. +> [!NOTE] +> The term "HVE Core" refers to different things depending on context: +> +> * **Repository** (`microsoft/hve-core`) - source for all 221 artifacts +> * **Extension** (`HVE Core`) - installs the flagship collection (41 artifacts) +> * **Extension** (`HVE Core All`) - installs all collections (221 artifacts) +> * **CLI plugin** (`hve-core`) - installable via `copilot plugin install hve-core@hve-core` +> +> Most users who only need Research, Plan, and Implement workflows should start with the **HVE Core** extension. To explore all domains, install **HVE Core All** instead. + +### How the Pieces Fit Together + +```mermaid +graph LR + REPO["microsoft/hve-core
(source repository)"] + REPO --> C1["hve-core
(flagship collection)"] + REPO --> C2["ado, github, security...
(domain collections)"] + C1 --> EXT1["HVE Core Extension
(41 artifacts)"] + C1 --> EXT2["HVE Core All Extension
(221 artifacts)"] + C2 --> EXT2 +``` + +### Which Extension Should I Install? + +* **I want to try it out quickly** → Install **HVE Core All** (everything included, explore at your pace) +* **I only need Research, Plan, Implement workflows** → Install **HVE Core** (flagship, 41 artifacts) +* **My team needs specific domains only** → Install **HVE Installer** (pick collections individually) +* **I want to contribute or modify source** → Clone the repository (see [Developer Setup](#developer-setup)) + ## Collection Packages HVE Core organizes artifacts into role-based collections. The VS Code extension installs the **HVE Core Workflow** collection (flagship RPI workflow and core artifacts). For the complete set across all collections, use the `hve-core-all` CLI plugin or installer skill. Clone-based methods also support filtering which agents to copy by collection bundle. diff --git a/docs/getting-started/methods/cli-plugins.md b/docs/getting-started/methods/cli-plugins.md index e462fcf9a..8036ac07b 100644 --- a/docs/getting-started/methods/cli-plugins.md +++ b/docs/getting-started/methods/cli-plugins.md @@ -107,6 +107,73 @@ project's `.github/instructions/` directory. * Skills require skill-compatible agent environments +## Using Agents After Installation + +After installing a plugin, agents and named commands are available in your CLI session. + +### Named Commands vs Agent Mode + +CLI plugins provide two distinct interaction patterns: + +| Mode | Command | Behavior | +|---------------|--------------------------|--------------------------------------------------------------| +| Named Command | `/git-commit` | Executes a predefined workflow, then returns to default mode | +| Agent Mode | `/agent Task Researcher` | Switches to the agent for open-ended conversation | + +Named commands (prompts) run a specific workflow and produce structured output. Agent mode enables freeform conversation with a specialized agent until you exit. + +> [!IMPORTANT] +> The CLI does not support prompts that switch to a custom agent directly. +> Prompts like `/task-research` are designed to run within a specific agent +> context. To use them, first switch to the agent, then run the prompt: +> +> ```text +> /agent Task Researcher +> /task-research topic="API authentication patterns" +> ``` +> +> Prompts that do not require an agent context (e.g., `/git-commit`, +> `/git-merge`) work directly from the default mode. + +### Example: Research Workflow + +Switch to the agent first, then run the prompt: + +```text +> /agent Task Researcher +Switched to Task Researcher +> /task-research topic="API authentication patterns" +[Agent executes research workflow, creates research document] +``` + +Continue with follow-up questions in the same agent context: + +```text +> What are common API authentication patterns for REST APIs? +[Research conversation continues] +> How do OAuth2 and API keys compare for microservices? +[Follow-up within same agent context] +> /exit +``` + +### Available Agents + +After installing the hve-core plugin, these agents are available via `/agent `: + +* Task Researcher - deep research and technical investigation +* Task Planner - implementation planning with phased execution +* Task Implementor - code changes following plans +* Memory - persistent context across sessions +* PR Review - pull request analysis and feedback + +For the complete list, run `/help` in a CLI session to see all available commands and agents. + +### When to Use Each Mode + +* Use **named commands** (`/git-commit-message`, `/git-merge`) directly from default mode for workflows that do not require a custom agent. +* Use **agent mode** (`/agent `) first, then run agent-specific prompts (`/task-research`, `/task-plan`) for structured workflows that need agent context. +* Stay in **agent mode** for exploratory conversations, follow-up questions, or tasks that don't fit a predefined prompt. + ---