You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: improve new user onboarding with terminology, CLI plugins, and collections clarity (#1520)
## Description
Improved the new user experience across the README, getting started
docs, and CLI plugin documentation based on [user research
findings](#1519). The
research identified 18 unanswered questions after reading the README, a
critical naming collision where "hve-core" is used in 4 distinct
contexts, and zero documentation on how to use agents after CLI plugin
installation.
### README Improvements
> Addressing the "30-second test" failures: users could identify what
HVE Core is and how to install it, but couldn't grasp key terminology or
discover the CLI installation path.
- Expanded **Hypervelocity Engineering** with a parenthetical definition
and replaced "constraint-based" with "convention-driven" plus an inline
explanation
- Added **one-click install badges** using `vscode:extension/` URI
scheme for both flagship and all-collections extensions
- Added **CLI plugin installation** path in Quick Start for Copilot CLI
users with marketplace registration and install commands
- Added **collections context** paragraph with RPI acronym expansion
before the extension comparison table
- Added **component-types callout** after the What's Included table
defining agents, prompts, instructions, and skills
### CLI Post-Install Usage
(*docs/getting-started/methods/cli-plugins.md*)
> Filling the critical gap: users had zero guidance on what to do after
`copilot plugin install` succeeds.
- Added "Using Agents After Installation" section documenting **named
commands vs agent mode** interaction patterns
- Documented the CLI limitation that **agent-specific prompts require
switching to the agent first** via `/agent <name>`
- Added example workflows showing the correct sequence and follow-up
conversation patterns
- Listed available agents from the flagship collection with one-line
descriptions
### Collections Disambiguation (*docs/getting-started/install.md*)
- Added **NOTE callout** disambiguating "HVE Core" across repository,
flagship extension, and all-collections extension contexts
- Added **Mermaid diagram** showing the repository → collections →
extensions relationship
- Added **decision aid** ("Which Extension Should I Install?") mapping 4
user scenarios to recommended paths
### Post-Install Activation (*docs/getting-started/collections.md*)
- Added "After Installing a Collection" section explaining **automatic
artifact activation** across all 4 component types
- Documented verification steps and path to adding more collections
later
## Related Issue(s)
Related to #1519
## Type of Change
Select all that apply:
**Code & Documentation:**
* [ ] Bug fix (non-breaking change fixing an issue)
* [ ] New feature (non-breaking change adding functionality)
* [ ] Breaking change (fix or feature causing existing functionality to
change)
* [x] Documentation update
**Infrastructure & Configuration:**
* [ ] GitHub Actions workflow
* [ ] Linting configuration (markdown, PowerShell, etc.)
* [ ] Security configuration
* [ ] DevContainer configuration
* [ ] Dependency update
**AI Artifacts:**
* [ ] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
* [ ] Copilot instructions (`.github/instructions/*.instructions.md`)
* [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
* [ ] Copilot agent (`.github/agents/*.agent.md`)
* [ ] Copilot skill (`.github/skills/*/SKILL.md`)
> Note for AI Artifact Contributors:
>
> * Agents: Research, indexing/referencing other project (using standard
VS Code GitHub Copilot/MCP tools), planning, and general implementation
agents likely already exist. Review `.github/agents/` before creating
new ones.
> * Skills: Must include both bash and PowerShell scripts. See
[Skills](../docs/contributing/skills.md).
> * Model Versions: Only contributions targeting the **latest Anthropic
and OpenAI models** will be accepted. Older model versions (e.g.,
GPT-3.5, Claude 3) will be rejected.
> * See [Agents Not
Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).
**Other:**
* [ ] Script/automation (`.ps1`, `.sh`, `.py`)
* [ ] Other (please describe):
## Sample Prompts (for AI Artifact Contributions)
<!-- Not applicable - documentation-only changes -->
## Testing
- Verified all changed files follow existing naming conventions
- Confirmed Mermaid diagram syntax is valid
- Validated badge URLs use correct shields.io format and
vscode:extension/ URI scheme
- CLI commands match patterns established in existing cli-plugins.md
documentation
- Manual review of rendered markdown formatting for callouts, tables,
and code blocks
- Automated validation deferred to CI pipeline
## Checklist
### Required Checks
* [x] Documentation is updated (if applicable)
* [x] Files follow existing naming conventions
* [x] Changes are backwards compatible (if applicable)
* [ ] Tests added for new functionality (if applicable) (N/A —
documentation-only changes)
### AI Artifact Contributions
<!-- If contributing an agent, prompt, instruction, or skill, complete
these checks -->
* [ ] Used `/prompt-analyze` to review contribution
* [ ] Addressed all feedback from `prompt-builder` review
* [ ] Verified contribution follows common standards and type-specific
requirements
### Required Automated Checks
The following validation commands must pass before merging:
* [x] Markdown linting: `npm run lint:md`
* [x] Spell checking: `npm run spell-check`
* [ ] Frontmatter validation: `npm run lint:frontmatter`
* [ ] Skill structure validation: `npm run validate:skills`
* [ ] Link validation: `npm run lint:md-links`
* [ ] PowerShell analysis: `npm run lint:ps`
* [ ] Plugin freshness: `npm run plugin:generate`
* [ ] Docusaurus tests: `npm run docs:test`
## Security Considerations
<!-- ⚠️ WARNING: Do not commit sensitive information such as API keys,
passwords, or personal data -->
* [x] This PR does not contain any sensitive or NDA information
* [ ] Any new dependencies have been reviewed for security issues (N/A —
no dependency changes)
* [ ] Security-related scripts follow the principle of least privilege
(N/A — no script changes)
---------
Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Bill Berry <WilliamBerryiii@users.noreply.github.com>
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.
27
+
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.
28
28
29
29
> [!TIP]
30
30
> Install from the VS Code Marketplace in under 30 seconds. See the [Installation Guide](docs/getting-started/install.md) for all options.
31
31
32
32
## Quick Start
33
33
34
-
1. Install the [HVE Core extension](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) from the VS Code Marketplace.
1. Install the [HVE Core - Flagship Collection extension](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) from the VS Code Marketplace.
35
39
2. Open any project and launch GitHub Copilot Chat (`Ctrl+Alt+I`).
36
40
3. Select an agent from the picker (try **rpi-agent**, **task-researcher**, or **memory**) and start a conversation.
37
41
38
42
That's it. Agents, instructions, and prompts activate automatically once the extension is installed.
39
43
44
+
**Using GitHub Copilot CLI?** Install as a plugin instead:
45
+
46
+
```bash
47
+
copilot plugin marketplace add microsoft/hve-core
48
+
copilot plugin install hve-core@hve-core
49
+
```
50
+
51
+
See [CLI Plugins](docs/getting-started/methods/cli-plugins.md) for usage details.
52
+
40
53
Ready for more? Follow the [Getting Started Guide](docs/getting-started/README.md).
41
54
42
55
## Choose Your Extension
43
56
44
57
Two VS Code extensions serve different needs:
45
58
59
+
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).
|[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 |
49
64
|[HVE Installer](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-installer)| Selective installation of specific collections | Teams that want to pick only the collections relevant to their workflow |
50
65
51
66
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.
52
67
68
+
**Copilot CLI users:** All collections are also available as [CLI plugins](docs/getting-started/methods/cli-plugins.md) via `copilot plugin install <collection>@hve-core`.
Copy file name to clipboardExpand all lines: docs/getting-started/collections.md
+13Lines changed: 13 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -95,6 +95,19 @@ If you prefer a leaner workspace or need to standardize which artifacts are avai
95
95
> [!TIP]
96
96
> 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.
97
97
98
+
## After Installing a Collection
99
+
100
+
Once a collection is installed, its artifacts activate automatically:
101
+
102
+
1. Agents appear in the Copilot Chat agent picker (press `Ctrl+.` or use the dropdown).
103
+
2. Prompts are available as slash commands (type `/` in Copilot Chat to see them).
104
+
3. Instructions apply automatically to matching files based on their `applyTo` patterns.
105
+
4. Skills extend agent capabilities without additional configuration.
106
+
107
+
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.
108
+
109
+
To add more collections later, search "HVE" in the VS Code Extensions marketplace or use the selective install commands from the table above.
> 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.
C1 --> EXT2["HVE Core All Extension<br/>(221 artifacts)"]
85
+
C2 --> EXT2
86
+
```
87
+
88
+
### Which Extension Should I Install?
89
+
90
+
***I want to try it out quickly** → Install **HVE Core All** (everything included, explore at your pace)
91
+
***I only need Research, Plan, Implement workflows** → Install **HVE Core** (flagship, 41 artifacts)
92
+
***My team needs specific domains only** → Install **HVE Installer** (pick collections individually)
93
+
***I want to contribute or modify source** → Clone the repository (see [Developer Setup](#developer-setup))
94
+
66
95
## Collection Packages
67
96
68
97
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.
| Named Command |`/git-commit`| Executes a predefined workflow, then returns to default mode |
121
+
| Agent Mode |`/agent Task Researcher`| Switches to the agent for open-ended conversation |
122
+
123
+
Named commands (prompts) run a specific workflow and produce structured output. Agent mode enables freeform conversation with a specialized agent until you exit.
124
+
125
+
> [!IMPORTANT]
126
+
> The CLI does not support prompts that switch to a custom agent directly.
127
+
> Prompts like `/task-research` are designed to run within a specific agent
128
+
> context. To use them, first switch to the agent, then run the prompt:
[Agent executes research workflow, creates research document]
147
+
```
148
+
149
+
Continue with follow-up questions in the same agent context:
150
+
151
+
```text
152
+
> What are common API authentication patterns for REST APIs?
153
+
[Research conversation continues]
154
+
> How do OAuth2 and API keys compare for microservices?
155
+
[Follow-up within same agent context]
156
+
> /exit
157
+
```
158
+
159
+
### Available Agents
160
+
161
+
After installing the hve-core plugin, these agents are available via `/agent <name>`:
162
+
163
+
* Task Researcher - deep research and technical investigation
164
+
* Task Planner - implementation planning with phased execution
165
+
* Task Implementor - code changes following plans
166
+
* Memory - persistent context across sessions
167
+
* PR Review - pull request analysis and feedback
168
+
169
+
For the complete list, run `/help` in a CLI session to see all available commands and agents.
170
+
171
+
### When to Use Each Mode
172
+
173
+
* Use **named commands** (`/git-commit-message`, `/git-merge`) directly from default mode for workflows that do not require a custom agent.
174
+
* Use **agent mode** (`/agent <name>`) first, then run agent-specific prompts (`/task-research`, `/task-plan`) for structured workflows that need agent context.
175
+
* Stay in **agent mode** for exploratory conversations, follow-up questions, or tasks that don't fit a predefined prompt.
0 commit comments